@apertura/viewer

Base class for every error raised by Apertura. A common ancestor lets consumers distinguish "the file failed to open" from a genuine bug in their own code with a single `instanceof` check.

An extracted document: the tree, and every way of writing it down. The serialisers are methods rather than free functions for one reason: the addresses. A caller who has the tree and reaches for a `render` from somewhere else gets text with no way back into the document, which is the thing this package exists to prevent. Everything that produces text from here can also produce the map beside it.

The file was identified, but its contents violate the format specification.

Registry of parsers. An instance rather than a global singleton: a single page may host several independently configured viewers, and tests must not see each other's registrations. {@link defaultRegistry} is available for simple cases. Renderers are registered in `ViewRegistry` from `@apertura/render`, which extends this class. The split is what lets a server open a document without the DOM appearing anywhere in the type graph.

A format feature that has not been implemented yet. A dedicated type lets the viewer show "this part of the document is not supported yet" instead of a generic read failure.

The file format was not recognised, or no plugin is registered for it.

A framework-independent document viewer. The single place that knows the full path from bytes to format to document to DOM. The React, Vue and Angular wrappers are thin adapters over this class, so their behaviour is identical by construction rather than by convention.

A format registry that also knows how to draw. Parsers are registered in `@apertura/core`, which knows nothing about the browser; renderers are registered here. Subclassing rather than composing keeps the fluent chain a caller expects — `registerParser` returns `this`, so a registry can be built in one expression — while leaving the parser half usable on a server that has no DOM at all.

A registry with every supported format registered. The convenient entry point for an application that just needs to open a file. When bundle size matters, build a {@link ViewRegistry} by hand so only the parsers actually used are included.

A registry holding only the Word format, for applications that need just that.

Builds the search index for a document already on screen. The bytes are wanted but not required. With them the addresses carry a hash and a stored anchor from a different file is refused rather than resolved to whatever sits at that path; without them everything still works and simply cannot warn.

Creates a viewer mounted into the given element.

Determines the file format from its contents, name and MIME type. For ZIP containers the result is always `probable`: telling docx, xlsx, pptx and odt apart requires looking inside the archive, which is the job of `@apertura/ooxml`. The core deliberately avoids pulling in decompression just to detect a format.

Read a document's content. Takes anything a byte source can be made of — a path is not one of them, that is `@apertura/node` — or an already-open document, which is the path a viewer takes when it wants to search what is already on screen without parsing it twice.

The whole document as markdown, in one call.

The whole text, in one call. The shortest path in and the one most people will take first, so it does the conventional thing without being asked: no section labels, no markers, no markup.

Plain search over a document, returning anchors rather than offsets. What the viewer's find box is built on. Everything it returns is a selector set, so a hit found here highlights through exactly the same path as a chunk retrieved from a vector database — one mechanism, not two.

Read the content of a document that is already open. The viewer's path. A hash is computed from the bytes when they are to hand and omitted otherwise — an address with no hash still resolves, it simply cannot warn that it came from a different file.

Normalises any supported input into a {@link ByteSource}. Strings are URLs.

An opened document: the contract shared by every parser. Deliberately narrow — it only carries what is meaningful for any format. Everything else (docx sections, xlsx sheets, pptx slides) lives in subtypes inside the format packages. The viewer works against this interface so that it can still show a title and a page count for a format whose renderer is not registered.

A random-access source of bytes. This is the central abstraction of the project: parsers never touch `File`, `Blob` or the network directly. That makes it possible to read a ZIP central directory at the end of a file, or a PDF xref table, without pulling the whole document into memory, and to run the same parser in a browser, in Node, or on top of HTTP range requests.

Chunking that knows what a document is. The state of the art in JavaScript is to take the text, split it every 512 characters, and hope. That destroys exactly the things retrieval depends on: a table loses its header three rows in, a heading is separated from the section it names, a sentence is cut in half, and every chunk arrives at the index with no idea where it came from. This walks the tree instead. Headings become breadcrumbs and stay with their content, a table row is never split, a table too big for one chunk is split by rows with its header repeated in each, and every chunk carries the selectors that find it again in the document it came from — which is the part nobody else has, and the reason a retrieval hit can be highlighted rather than merely quoted.

Result of format detection.

Metadata common to every format.

A live view of a document mounted into the DOM.

What to do with the things that are not words. The defaults are chosen for the commonest use, which is feeding a language model, and they are not the conservative choices. `charts: 'data'` reads a chart out as the numbers it plots, because a chart is a table and leaving a hole where one was is how every other extractor in this space loses the content of a quarterly report. `headers: 'first'` drops the running head repeated on every page, because eighty repetitions of a company name is what poisons a retrieval index.

Highlights, as state rather than as an operation. This is the design decision virtualisation forces, and it is not a detail. Only the pages near the viewport exist in the DOM — that is what lets a thousand-page document open as quickly as a five-page one — so "highlight this passage" cannot mean "find it and paint it". The passage is usually not there yet. So a highlight is a registered intention. The registry keeps it, paints what is currently on the page, and repaints when the page changes: a scroll, a zoom, a mount. Add a highlight on page four hundred of an unopened document and nothing visible happens until page four hundred arrives, at which point it is already there. The other thing that falls out of this: a highlight is a *list of fragments*, never a rectangle. A paragraph split between page three and page four gives two groups of rectangles on two pages, and an API that promised one would have to be rewritten the first time somebody highlighted a long quotation.

Semantic HTML: the structure, not the appearance. Not a renderer, and the distinction is the whole design. `@apertura/docx-view` reproduces what a document looks like — fonts, page boxes, measured line breaks. This produces what it *is*: headings that are headings, tables that are tables, a `<figure>` around a picture and its caption. There is no CSS and no colour, because the consumer is a language model, a search index, or a page that has its own stylesheet and does not want this one. Every element carries its address in `data-loc`, which is what makes an HTML extraction round-trip: a click in the rendered output can be turned back into a place in the document.

Markdown, written properly. The bar is not "produces something a renderer accepts". Every library in this space clears that. The bar is that a person reading the output can tell what the document said, and a language model reading it does not have to guess — which means the table alignment survives, the nested list stays nested, a pipe inside a cell does not end the column, a paragraph starting with `1.` does not silently become a list, and a footnote is a footnote rather than a number floating in the middle of a sentence. Every one of those is a bug this had at some point.

Options shared by every parser.

A resolution, and how much to trust it. `resolvedBy` is not decoration. An application that watches it can see its documents drifting — the day the exact selectors stop matching and everything falls through to quotes is the day somebody started editing the corpus — and it can see that before a user reports a highlight in the wrong place.

Search and highlighting, over one mechanism rather than two. The temptation is to write a find box that walks the DOM looking for a string, which every viewer has, and which is wrong here for three reasons: it cannot see the pages that are not mounted, it finds the list numbers and page numbers the renderer computed, and what it produces is a DOM node rather than an address — so a hit cannot be stored, sent anywhere, or found again after a relayout. Instead the search runs over the extracted text, which the extractor can produce in the browser because it depends on nothing that is not there. A hit is a range of that text, which is an address, which is a highlight. The same path a chunk retrieved from a vector database takes. So `find` and `showChunk` are the same operation with different inputs, and neither had to be built twice.

Plain text: the output with nothing added. The one that has to be genuinely plain. It is what goes into a search index, a diff, a `grep`, and every pipeline whose next stage is not a markdown parser — and every character of markup in it is a false hit waiting to happen. So the only characters here that are not from the document are the separators between blocks, and a caller who wants none of those can say so.

A renderer plugin: turns a parsed document into DOM.

Everything Apertura can turn into a {@link ByteSource}.

Broad document category; determines which viewer applies.

Identifier of a concrete file format. A string literal union rather than an enum: the values are part of the public API, get serialised to JSON, and are used as registry keys.

The opaque wire form. Parse it with {@link parseLocator}.

Viewer state; UI wrappers render indicators from it.

The docx parser plugin for {@link FormatRegistry }. `canOpen` looks inside the ZIP: the extension cannot be trusted, and every OOXML format shares one signature. Opening the package for the check is cheap — only the central directory and `[Content_Types].xml` are read — and the result is cached by the archive, so the subsequent `open` pays nothing twice.

The docx renderer plugin for {@link FormatRegistry }.

The default look, for a host that would rather not write any. Injected by the caller rather than by the registry: a viewer embedded in an application has a design system, and a package that put a stylesheet in the head without being asked would be fighting it. The colours are stated as custom properties so overriding one does not mean copying the rule. `::highlight()` accepts a short list of properties — colour, background, decoration and shadow — and nothing that affects layout, which is the point of it: a highlight cannot move the text it marks.