@onodocs/canvas 0.2.1 → 0.4.0

package/SDK.md

@@ -1,219 +1,407 @@
-# OnoDocs SDK
-
-`@onodocs/sdk` processes Word documents. Its default entry performs analysis in Node or a browser; `/browser` adds layout and immutable page publication using browser font services; `/server` runs that processing in headless Chromium. `@onodocs/canvas` paints prepared pages and provides the viewer, selection and DOM attachments. The Canvas package runs independently of the parser, semantic engine and layout engine.
-
-Supported Word inputs are DOCX, DOCM, DOTX and DOTM. Macro-enabled files are rendered without executing VBA. Older binary DOC/DOT files and RTF are not supported.
-
-Install with `npm install @onodocs/sdk @onodocs/canvas`. Use matching versions of both packages. A backend can install only the SDK; a frontend receiving prepared pages can install only Canvas. Both packages include TypeScript declarations and this guide. Archives are also available from the [public releases](https://github.com/onodocs/onodocs/releases). Server rendering requires an installed Chromium-family browser. The server adapter includes the Canvas runtime it uses for image and PDF export.
-
-Without a key, the SDK runs in free, non-production evaluation mode with full features and a watermark on rendered output. Pass `{ licenseKey }` to `openDocument` for a 30-day trial or commercial entitlement; this works in all three entry points. Verification is entirely offline. Commercial keys permit covered releases indefinitely, with renewal for later releases and support. Browser verification requires HTTPS or a secure local context. See the included `LICENSING.md` and `LICENSE` for details.
-
-## Inspect and query
-
-```ts
-import { openDocument } from "@onodocs/sdk";
-
-const doc = await openDocument(bytes);
-const customer = doc.query.contentControls().where({ tag: "customer-name" }).one();
-const cells = doc.query.tables().cells().all();
-const matches = doc.query.findText("Invoice total").all();
-const headers = doc.query.stories().where({ story: "header" }).paragraphs().all();
-```
-
-TypeScript completion shows valid paths and filters. Select a kind, narrow with `where`, then choose how many results you expect:
-
-| Method | Result |
-| --- | --- |
-| `one()` | One match; throws for zero or multiple matches |
-| `optional()` | One match or undefined; throws for multiple matches |
-| `first()` / `at(index)` | An explicitly chosen match or undefined |
-| `all()` / iteration | Every match in document traversal order |
-| `count()` | Number of matches |
-| `map(project)` | Project matches into application data |
-
-Selectors (`paragraphs`, `runs`, `tables`, `contentControls`, `bookmarks`, `stories`) search descendants. `rows` selects a table's own rows; `cells` selects a table or row's own cells. Nested tables are selected separately with `tables()`. Typed element collections also allow `table.rows[0].cells[1]`. `children()` and `descendants()` provide generic traversal. Scope an existing element with `doc.query.within(element)`. Nested or overlapping selections never duplicate the same element. A story represents an authored story; a reused header remains one semantic story with several physical occurrences.
-
-`where({ text: "Total" })` matches exactly and case sensitively. Use `where({ text: { contains: "Total" } })`, `startsWith`, or `endsWith` for other matches. Multiple fields and chained filters combine with AND. Paragraphs support `style`; content controls support `tag` and `title`; bookmarks support `name`; stories support `story` (`body`, `header`, `footer`, `footnote`, `endnote`, `textbox`). Unknown keys fail instead of silently returning unexpected content. Use `.filter(element => ...)` for application predicates.
-
-`doc.query.get(id)` resolves an element in the current snapshot. Every element has a `parent`; `doc.query.within(element).closest("cell")` finds its containing cell, including the input itself if it is a cell. Negative query indices count from the end.
-
-`findText("...")` or `findText(/pattern/i)` searches contiguous text in selected paragraphs or runs, including text split across runs. It returns a paragraph and a half-open `[start, end)` range in JavaScript UTF-16 offsets. It does not join separate paragraphs. Regular expressions search each selected contiguous interval, preserve the caller's lastIndex, and omit zero-length matches. Queries preserve the selected revision view. Semantic text includes authored content; generated fields and physical appearances can differ after layout. Rasterized picture/chart text has no text query model.
-
-Bookmarks expose their published start target through `bookmark.run`; they do not represent an enclosing bookmark text range. Symbols without a Unicode text representation use the object replacement character in query text.
-
-## Replace text and fill templates
-
-```ts
-const customer = doc.query.contentControls().where({ tag: "customer" }).one();
-await doc.update({ target: customer, text: "Willow Design" });
-```
-
-`update` accepts one update or a batch. Targets are runs, paragraphs, cells, content controls, their IDs, or search ranges. Element targets must contain ordinary text in one paragraph. Replacement text inherits the first selected run’s formatting; other selected runs become empty. Tabs and newlines are supported. Batches reject overlapping or missing targets, generated fields, and multi-paragraph replacements without changing the document.
-
-Use search ranges for partial replacements while keeping surrounding text and formatting:
-
-```ts
-await doc.update(doc.query.findText("{{customer}}").map(target => ({ target, text: "Willow Design" })));
-```
-
-Batch range offsets refer to the original paragraph text. Empty ranges insert text; offsets must not split an emoji or other surrogate pair. Unchanged updates preserve existing formatting, snapshots, and attachments.
-
-Browser updates rebuild layout and refresh mounted views. Query, semantic, layout, page and geometry values obtained earlier remain snapshots; read them again after updating. Application attachments are removed during refresh and can be reattached using fresh geometry. Updates run in submission order and accept `{ signal }` for cancellation. The original `source` is unchanged.
-
-Node inspection exposes the same update method. For server rendering, inspect the input with the default entry point to select elements or ranges, then pass those updates to the server document before `renderPage` or `pdf`. Exports reflect the updated text. Saving an updated DOCX, structural editing, and field recalculation are not supported.
-
-## Render and attach ordinary DOM
-
-Mounted views include read-only text selection and plain-text copying. Drag or Shift-click to select text, extend with Shift and the arrow/Home/End keys, select all with Ctrl/Command+A, and copy with Ctrl/Command+C or the Copy context menu. Selection spans pages and survives scrolling and zoom, including pages whose canvases have been released. Document updates clear the previous selection. Attached inputs retain their normal editing and clipboard behavior.
-
-```ts
-import { openDocument } from "@onodocs/sdk/browser";
-import { createDocument } from "@onodocs/canvas";
-
-const doc = await openDocument(file);
-const canvasDocument = createDocument(doc);
-const view = canvasDocument.mount(container);
-const field = doc.query.contentControls().where({ tag: "customer-name" }).one();
-const input = document.createElement("input");
-input.name = "customerName";
-const attachment = view.attach(input, { anchor: doc.geometry.fragments(field)[0] });
-```
-
-The example requires a tagged control that produces one visible fragment. Call `doc.geometry.fragments(field)` for content spanning lines, pages, or repeated stories, and attach to an explicitly chosen fragment. Fragments retain transforms and clipping. Table/cell anchors use their final physical rectangles. `offset` and `size` optionally adjust attachment placement in page units. Values, validation, submission, focus, and accessibility labels belong to the application. Attaching an element moves it into the view. Detachment removes it and restores its original inline style. Reattaching the same HTML element disposes its previous attachment; old handles become inert. An attachment exposes its disposed state.
-
-Pages are anchors too. Placement avoids manual rectangle arithmetic:
-
-```js
-view.attach(checkbox, { anchor: doc.geometry.fragments(doc.query.findText("Client approval:").one())[0], placement: "outside-right", gap: 80, size: { width: 420, height: 420 } });
-view.attach(submitButton, { anchor: doc.pages[0], placement: "inside-bottom-right", inset: 480, size: { width: 2400, height: 600 } });
-```
-
-Inside placements use `inside-{top|center|bottom}-{left|center|right}` with optional `inset`. Outside placements use `outside-{top|right|bottom|left}` with optional `gap` and center the element along the selected edge. The default is `overlay`. All sizes, spacing and offsets use twips (1/1440 inch). Without a size, the element fills the anchor, reduced by the inset for inside placement. Offsets apply after placement. Content anchors retain their transforms and clips; page anchors use the full page. Attachments do not reflow text, so reserve room in the document.
-
-Adjacent styled runs on one line share a fragment. Fragment bounds enclose the unclipped geometry; the supplied clips determine which portions are visible.
-
-`view.setZoom("fit-width")` tracks container width. Numeric zoom uses 96 CSS pixels per inch at `1`. `view.toClient(pageIndex, point)` and `view.fromClient({ x: event.clientX, y: event.clientY })` translate coordinates. `view.hitTest(clientPoint)` returns `{ elementId, fragment, caret? }`. Resolve `elementId` with `doc.query.get(elementId)` when the processing SDK is available. Text hits resolve to a run or paragraph; table whitespace resolves to a cell or table. `caret` contains `{ paragraphId, offset, point }`, with the same UTF-16 offset convention as search ranges. Generated field text omits a caret when no source position can be represented. Raster drawings without a semantic hit identity and blank page space return no element.
-
-`view.scrollTo(anchor, { block: "center" })` reveals a page or a physical fragment. Resolve elements and text ranges through `doc.geometry.fragments(anchor)` first, then choose the occurrence to reveal.
-
-A run's optional `link` is `{ kind: "external", target, tooltip }` or `{ kind: "bookmark", target }`. Use bookmark queries and scrollTo for internal links. The host application decides whether and how to open external destinations.
-
-All page and query indices are **zero based**. Page geometry uses **twips: 1440 units per inch**. `await canvasDocument.pages[index].render(canvas, { dpi: 144 })` prepares the page resources and paints the canvas; `await doc.pages[index].load(signal)` returns the immutable page commands and their resources. Containers should have a usable width. Multiple views can share one document.
-
-Call `attachment.dispose()`, `view.dispose()`, `canvasDocument.dispose()`, or `doc.dispose()` when done. Canvas disposal removes its views and releases its font registrations. Processing disposal also disposes subscribed Canvas documents and releases processing resources. Models remain inspectable; further painting is rejected. Pass `{ signal }` when opening. Opening copies byte inputs; a File/Blob is read once by either the browser or analysis entry point. Fetch URLs in host code with the authentication policy your application needs, then pass bytes.
-
-## Show pages while processing
-
-Progress events expose a document source that the Canvas package can observe. Create the view once. Its subscription follows provisional page replacements and the completed layout.
-
-```ts
-import { openDocument } from "@onodocs/sdk/browser";
-import { createDocument, type CanvasDocument } from "@onodocs/canvas";
-
-let canvasDocument: CanvasDocument | undefined;
-const doc = await openDocument(bytes, {
-  signal,
-  onProgress(progress) {
-    canvasDocument ??= createDocument(progress.document, { container });
-    status.textContent = progress.stage;
-  },
-});
-```
-
-Cancelling or failing processing disposes the source and its subscribed view. After success, dispose `doc` when the application closes the document. A Canvas document can be disposed earlier without closing the processor.
-
-## Render on the server
-
-```ts
-import { readFile, writeFile } from "node:fs/promises";
-import { createRenderer } from "@onodocs/sdk/server";
-
-const renderer = await createRenderer({ channel: "chrome" });
-try {
-  const doc = await renderer.openDocument(await readFile("invoice.docx"));
-  try {
-    await writeFile("invoice.png", await doc.renderPage(0, { dpi: 144 }));
-    await writeFile("invoice.pdf", await doc.pdf({ dpi: 150 }));
-  } finally { await doc.dispose(); }
-} finally { await renderer.dispose(); }
-```
-
-Install Chromium/Chrome separately; use `executablePath` for a deployment-managed binary or `channel: "chrome"`/`"msedge"` for an installed browser. The renderer reuses one browser, with a separate context per document. PNG and JPEG output use the browser engine's Canvas path. PDF contains rasterized pages at their document sizes, including mixed sizes. It does not provide searchable PDF text or tagged-PDF accessibility.
-
-Contexts make no outbound network requests. Supply fonts as data URLs through `fonts`, or install them on the rendering host. Browser consumers can also supply font URLs. Embedded document fonts use the engine's existing resource path. Use identical browser versions and fonts when reproducible output matters.
-
-Opening and output methods accept an AbortSignal. Cancelling an active operation closes that document context; open a new document to retry. Cancelling an operation still waiting in the queue leaves the active operation and document intact. Both server documents and renderers expose `disposed`. Disposing the renderer closes all remaining documents. A renderer can open multiple documents concurrently; output requests on one document are serialized. Applications control scheduling and process isolation.
-
-## Process on the backend and render in the frontend
-
-The [complete backend viewer sample](https://github.com/onodocs/onodocs/tree/main/examples/backend-viewer) includes a Node.js server, working endpoints, a browser frontend and an authored DOCX. Install Node.js 22.18 or newer and Google Chrome, then run:
-
-```sh
-git clone https://github.com/onodocs/onodocs.git
-cd onodocs/examples/backend-viewer
-npm install
-npm start
-```
-
-Open http://127.0.0.1:5175. Use `npm start -- /path/to/document.docx` to open another server-side file. Stop the server with Ctrl+C. The [website guide](https://onodocs.com/developers/#combined) includes the complete server and frontend source.
-
-The server's `manifest({ format: "json" })` and `page(index, { format: "json" })` methods return response bodies ready to send with `Content-Type: application/json`. For a document at `/document`, serve its manifest there and individual pages at `/document/pages/:index`. The original methods without a format option still return typed objects for in-process use.
-
-```js
-import { openDocument } from "@onodocs/canvas";
-
-const doc = await openDocument("/document", {
-  container: document.querySelector("#pages"),
-  viewOptions: { zoom: "fit-width" }
-});
-await doc.view.whenRendered();
-```
-
-Canvas handles loading and decoding. It requests page content as needed. `signal` cancels requests; `request` accepts fetch options such as `headers` and `credentials` for both the manifest and page requests. Same-origin cookies work by default. Requests default to no-store, and non-successful HTTP responses reject with the status code. Dispose the Canvas document when closing or replacing the view.
-
-The application owns the endpoints and document authorization. Keep server documents open while their endpoints are in use, then dispose them. For updates, publish each completed snapshot at its own URL and reopen the frontend view. Use matching SDK and Canvas releases.
-
-Selection, copying, hit testing, zoom and attachments use the published geometry. Queries and updates stay on the backend. The frontend receives the visible text and resources needed to display the document. Supplied and embedded fonts travel with the pages; fonts resolved from the server's installed fonts must also be available on the client.
-
-## Errors and application data
-
-Opening, updating, and exporting can reject. Handle errors at your application boundary and dispose browser/server resources in finally blocks. The analysis and browser entries export `PackageOperationError`, `SemanticOperationError`, and `QueryCardinalityError`; cancellation uses the signal's reason.
-
-Query elements are readonly in-memory models with parent references, source metadata, and bigint values. Project the fields your application needs instead of serializing the entire model:
-
-```ts
-const paragraphs = doc.query.stories().where({ story: "body" }).paragraphs()
-  .map(({ id, text, style }) => ({ id, text, style }));
-const json = JSON.stringify(paragraphs);
-```
-
-The same projection supports AI context, search indexing, and backend messages without coupling your data format to engine internals.
-
-## Low-level stages
-
-`doc.source` is the typed source model and `doc.semantic` contains completed document meaning. Element `source` locations refer into `doc.source.sourceFacts` and provenance. These identifiers belong to that loaded document, not arbitrary later revisions. The models describe supported DOCX content; they do not preserve every XML detail for round-trip writing.
-
-The main SDK also exports the core stage APIs: `parseDocumentSource`, `createSemanticDocument`, `parseDocumentForRendering`, font preparation, `createLayoutDocument`, and `createPageDisplayList`. Low-level `materializePageDisplayListToCanvas` is exported by `@onodocs/canvas`. Advanced consumers can stop at a stage or replay paint through their own adapter. Use canonical readonly contracts; do not mutate stage outputs. Layout remains the authority for all physical geometry.
-
-### Extract a table as text
-
-```ts
-const data = doc.query.tables()
-  .where({ headers: ["Deliverable", "Owner", "Due"] })
-  .one().textRows;
-```
-
-`textRows` includes the first row and keeps cells grouped by their own table rows. The header filter matches the first row exactly, in order and case sensitively; it does not infer header formatting. Nested tables remain text inside their containing cells. Merged cells retain authored topology; the result is not padded into a rectangular grid. Use `data.slice(1)` to omit the header. The readonly matrix is a snapshot; query again after an update.
-
-## Large documents
-
-Use the progress subscription shown above to display early pages while layout continues. Early pages are provisional: page counts, fields, notes and placement can change as formatting settles. Opening resolves with the complete document. Abort the loading signal to dispose the source and its subscribed views.
-
-Mounted views paint the visible neighborhood and release distant canvas pixels. Zoom and scrolling render pages on demand. Decoded images are acquired only for a page render and released afterward. Parsing and document layout still require memory proportional to document content; virtualization does not make the document model constant-memory. Auto-fit tables and document-wide fields can require later content before their output settles.
-
-Await page renders before reading or exporting the canvas:
-
-```js
-await canvasDocument.pages[0].render(canvas, { dpi: 144, signal: controller.signal });
-const png = canvas.toDataURL("image/png");
-```
+# OnoDocs SDK
+
+Try the [proposal studio](proposal.md) for a runnable business-data, Word-template, editing and DOCX/PDF export workflow.
+
+See [document modes](document-modes.md) for viewing, editing, reviewing and form filling in one session.
+
+For form authoring, controlled answer regions and completed DOCX plus structured answers, see [document forms](document-forms.md).
+
+For application events, autosave, recovery, framework lifecycle and self-hosted HTTP, see [application integration](application-integration.md).
+
+`@onodocs/sdk` processes Word documents. Its default entry performs analysis in Node or a browser; `/browser` adds layout and immutable page publication using browser font services; `/server` runs that processing in headless Chromium. `@onodocs/canvas` paints prepared pages and provides the viewer, selection and DOM attachments. The Canvas package runs independently of the parser, semantic engine and layout engine.
+
+Supported Word inputs are DOCX, DOCM, DOTX and DOTM. Macro-enabled files are rendered without executing VBA. Older binary DOC/DOT files and RTF are not supported.
+
+Install with `npm install @onodocs/sdk @onodocs/canvas`. Use matching versions of both packages. A backend can install only the SDK; a frontend receiving prepared pages can install only Canvas. Both packages include TypeScript declarations and this guide. Archives are also available from the [public releases](https://github.com/onodocs/onodocs/releases). Server rendering requires an installed Chromium-family browser. The server adapter includes the Canvas runtime it uses for image and PDF export.
+
+Without a key, the SDK runs in free, non-production evaluation mode with full features and a watermark on rendered output. Pass `{ licenseKey }` to `openDocument` for a 30-day trial or commercial entitlement; this works in all three entry points. Verification is entirely offline. Commercial keys permit covered releases indefinitely, with renewal for later releases and support. Browser verification requires HTTPS or a secure local context. See the included `LICENSING.md` and `LICENSE` for details.
+
+Optional [shared document collaboration](document-collaboration.md) adds multi-user editing and review with customer authentication, atomic persistence and recoverable local drafts. Ordinary browser sessions remain independent.
+
+## Inspect and query
+
+```ts
+import { openDocument } from "@onodocs/sdk";
+
+const doc = await openDocument(bytes);
+const customer = doc.query.contentControls().where({ tag: "customer-name" }).one();
+const cells = doc.query.tables().cells().all();
+const matches = doc.query.findText("Invoice total").all();
+const headers = doc.query.stories().where({ story: "header" }).paragraphs().all();
+```
+
+TypeScript completion shows valid paths and filters. Select a kind, narrow with `where`, then choose how many results you expect:
+
+| Method | Result |
+| --- | --- |
+| `one()` | One match; throws for zero or multiple matches |
+| `optional()` | One match or undefined; throws for multiple matches |
+| `first()` / `at(index)` | An explicitly chosen match or undefined |
+| `all()` / iteration | Every match in document traversal order |
+| `count()` | Number of matches |
+| `map(project)` | Project matches into application data |
+
+Selectors (`paragraphs`, `runs`, `tables`, `contentControls`, `bookmarks`, `stories`) search descendants. `rows` selects a table's own rows; `cells` selects a table or row's own cells. Nested tables are selected separately with `tables()`. Typed element collections also allow `table.rows[0].cells[1]`. `children()` and `descendants()` provide generic traversal. Scope an existing element with `doc.query.within(element)`. Nested or overlapping selections never duplicate the same element. A story represents an authored story; a reused header remains one semantic story with several physical occurrences.
+
+`where({ text: "Total" })` matches exactly and case sensitively. Use `where({ text: { contains: "Total" } })`, `startsWith`, or `endsWith` for other matches. Multiple fields and chained filters combine with AND. Paragraphs support `style`; content controls support `tag` and `title`; bookmarks support `name`; stories support `story` (`body`, `header`, `footer`, `footnote`, `endnote`, `textbox`). Unknown keys fail instead of silently returning unexpected content. Use `.filter(element => ...)` for application predicates.
+
+`doc.query.get(id)` resolves an element in the current snapshot. Every element has a `parent`; `doc.query.within(element).closest("cell")` finds its containing cell, including the input itself if it is a cell. Negative query indices count from the end.
+
+`findText("...")` or `findText(/pattern/i)` searches contiguous text in selected paragraphs or runs, including text split across runs. It returns a paragraph and a half-open `[start, end)` range in JavaScript UTF-16 offsets. It does not join separate paragraphs. Regular expressions search each selected contiguous interval, preserve the caller's lastIndex, and omit zero-length matches. Queries preserve the selected revision view. Semantic text includes authored content; generated fields and physical appearances can differ after layout. Rasterized picture/chart text has no text query model.
+
+Bookmarks expose their published start target through `bookmark.run`; they do not represent an enclosing bookmark text range. Symbols without a Unicode text representation use the object replacement character in query text.
+
+## Extract content for search and automation
+
+`extractDocument` returns JSON-safe content and Markdown with links back to the source document. It is available from the default SDK entry and `/browser` and makes no network requests. Applications can pass its output to their own search or AI service.
+
+```ts
+import { extractDocument } from "@onodocs/sdk";
+
+const extraction = extractDocument(doc, { stories: ["body"] });
+const json = JSON.stringify(extraction.content);
+const markdown = extraction.markdown;
+```
+
+The content tree retains stories, paragraphs, runs, tables, cells, content controls, hyperlink metadata and source references. Tables preserve authored header and merge information. Markdown uses pipe tables for simple tables and ordered cell passages for nested or merged tables. JSON preserves the full table structure. Paragraph headings use selected style IDs `Heading1` through `Heading9` by default; pass `headingStyles: { ReportTitle: 1, SectionTitle: 2 }` to replace that mapping. This does not infer headings from visual formatting. Omit `stories` to include all supported stories. Text has the same semantic and cached-field behavior as queries.
+
+Each extracted element has a `source` string. In a browser document, resolve it into the existing geometry API to scroll to or highlight the original passage:
+
+```ts
+const anchor = extraction.resolve(sourceFromSearchResult);
+const fragments = doc.geometry.fragments(anchor);
+```
+
+For partial passages, `extraction.reference(paragraphSource, start, end)` creates a source reference with UTF-16 text offsets. To apply a reviewed automation result, use the existing edit commands without a selection field:
+
+```ts
+await extraction.edit(sourceFromReviewedResult, { kind: "replace", text: replacement });
+const bytes = await doc.save();
+```
+
+Editing accepts paragraph or text-range references and has the same supported-content restrictions as `doc.edit`. Formatting and authoring commands work through the same method. `extraction.selection(source)` returns a logical selection for application controls; `editor.select(selection)` followed by `editor.execute(command)` preserves the editor's undo history.
+
+References belong to one extraction snapshot. After a committed change or disposal, `extraction.stale` is true and reference operations throw `StaleDocumentReferenceError`. Re-extract before applying another result. The check also runs inside the edit queue, so a concurrent edit cannot redirect a delayed automation result to shifted text. Failed changes and no-op text updates preserve references. Saving alone preserves them; reopening requires a new extraction. Source links are not persistent document identities, and content remains readable after its references become stale.
+
+The [report review example](https://github.com/ionoy/onodocs/blob/main/docs/ai-report-demo.md) combines extraction, citations, reviewed edits and Word/PDF export. Its local sample reviewer can be replaced with the host's AI service.
+
+## Design and generate Word templates
+
+Use `createTemplateEditor` from `@onodocs/sdk/editor` for visual field authoring and preview. `openTemplate` and `templateTag` from the default SDK and browser entries support fields, repeated content, conditions, images, formatted values, reusable sections and batch generation. See [Word templates and generation](templates.md) for the binding model, authoring commands and output workflow.
+
+## Replace text and fill templates
+
+```ts
+const customer = doc.query.contentControls().where({ tag: "customer" }).one();
+await doc.update({ target: customer, text: "Willow Design" });
+```
+
+`update` accepts one update or a batch. Targets are runs, paragraphs, cells, content controls, their IDs, or search ranges. Element targets must contain ordinary text in one paragraph. Replacement text inherits the first selected run’s formatting; other selected runs become empty. Tabs and newlines are supported. Batches reject overlapping or missing targets, generated fields, and multi-paragraph replacements without changing the document.
+
+Use search ranges for partial replacements while keeping surrounding text and formatting:
+
+```ts
+await doc.update(doc.query.findText("{{customer}}").map(target => ({ target, text: "Willow Design" })));
+```
+
+Batch range offsets refer to the original paragraph text. Empty ranges insert text; offsets must not split an emoji or other surrogate pair. Unchanged updates preserve existing formatting, snapshots, and attachments.
+
+Browser updates rebuild layout and refresh mounted views. Query, semantic, layout, page and geometry values obtained earlier remain snapshots; read them again after updating. Application attachments are removed during refresh and can be reattached using fresh geometry. Updates run in submission order and accept `{ signal }` for cancellation. The original `source` is unchanged.
+
+Node inspection exposes the same update method. For server rendering, inspect the input with the default entry point to select elements or ranges, then pass those updates to the server document before `renderPage`, `pdf`, or `save`. Exports reflect the updated text.
+
+## Save an edited Word document
+
+`save()` returns DOCX bytes in Node, the browser, and server rendering. It refreshes supported fields, including after text edits or template generation. Use `save({ fields: "preserve" })` to retain cached field results; an unedited document then returns its original bytes. Text edits preserve surrounding run formatting and unedited package content. Saving and updating run in submission order. Both accept `{ signal }`; cancellation leaves the committed document available. Call `dispose()` when finished, including for Node documents, to release the preserved source package.
+
+`await doc.fieldStatus()` reports which fields can be updated, which require layout, and which are locked, static or unsupported. Node inspection updates supported sequences, text bookmark references and document properties. Browser and server documents also calculate page numbers, page references and supported tables of contents. Unsupported fields keep their cached values. Saving reports these through `onFieldStatus`, or a console warning when no callback is provided. Signed or protected packages remain unchanged when their fields cannot be written. `save({ fields: "require-current" })` throws `DocumentFieldUpdateError` if a field cannot be refreshed. PDF export accepts the same field policy and diagnostic callback.
+
+```js
+import { readFile, writeFile } from "node:fs/promises";
+import { openDocument } from "@onodocs/sdk";
+
+const doc = await openDocument(await readFile("template.docx"));
+try {
+  await doc.update({
+    target: doc.query.contentControls().where({ tag: "customer" }).one(),
+    text: "Willow Design"
+  });
+  await writeFile("completed.docx", await doc.save());
+} finally {
+  doc.dispose();
+}
+```
+
+In a browser, create a Blob from the returned bytes with type `application/vnd.openxmlformats-officedocument.wordprocessingml.document`. In a combined deployment, serve `await doc.save()` from an application-owned download endpoint with that content type and a `.docx` filename. The backend processing document owns saving; a Canvas-only frontend does not contain the original Word package.
+
+The SDK package includes a complete command-line example. After installing it, run `node node_modules/@onodocs/sdk/examples/fill-template.mjs template.docx completed.docx customer "Willow Design"`. Set `ONODOCS_LICENSE_KEY` for trial or commercial use. The source workspace keeps the same example at `examples/fill-template.mjs`.
+
+The initial editing profile covers ordinary text and unbound text or rich-text content controls within one paragraph, including supported tables, headers, footers and notes. Edits inside bound or content-locked controls, temporary or specialized controls, fields, revisions, alternate-content branches, and source runs with generated or unsupported content are rejected before publication. Plain-text controls that disallow multiple lines reject newlines. Filling an unbound text control clears its placeholder-display flag. Edits elsewhere preserve these constructs. `DocumentSaveError.reason` identifies source-writing restrictions; existing semantic target errors remain `RangeError`.
+
+Signed packages, enforced document protection, macro-enabled documents and templates retain their editing restrictions. Ordinary text updates reject documents with change tracking enabled; use the review operations below to author tracked replacements and formatting. Saving refreshes supported fields under the selected field policy. Original authored formatting is preserved independently of rendering compatibility decisions.
+
+Evaluation exports contain the full Word document without adding a Word watermark. The existing non-production evaluation terms apply; rendered evaluation output continues to include its watermark.
+
+## Edit formatting and paragraphs
+
+`edit()` accepts a logical selection with paragraph IDs and UTF-16 offsets. It returns the selection in the resulting document. Use fresh queries after editing because structural operations rebuild the document and its IDs. The `source` getter then describes the new committed package.
+
+```js
+const paragraph = doc.query.paragraphs().first();
+let selection = {
+  start: { paragraphId: paragraph.id, offset: 0 },
+  end: { paragraphId: paragraph.id, offset: paragraph.text.length }
+};
+selection = await doc.edit({ kind: "format", selection, formatting: { bold: true, fontSize: 18 } });
+selection = await doc.edit({ kind: "replace", selection, text: "First paragraph\nSecond paragraph" });
+await doc.edit({ kind: "align", selection, alignment: "center" });
+const bytes = await doc.save();
+```
+
+Character formatting supports `bold`, `italic`, `underline`, `strike`, `fontSize` in points, `fontFamily`, and `color` as `#RRGGBB`. Values change direct formatting on the selected text while preserving the other authored properties. `run.formatting` exposes the common effective character properties for controls; `paragraph.alignment` exposes left, center, right or justified alignment. These convenience properties describe ordinary Latin text; they do not replace the full semantic typography model for script-specific inspection.
+
+A replacement with a collapsed selection inserts text. Newlines split paragraphs; set `paragraphBreaks: false` for line breaks within a paragraph. Replacing a selection across adjacent paragraphs joins their surviving prefix and suffix. Empty text deletes the selection. New text inherits the starting run's formatting unless the operation includes `formatting`. Split paragraphs inherit the starting paragraph's properties. The first paragraph's properties win when joining.
+
+Rich editing supports ordinary text paragraphs, including empty paragraphs and paragraphs in table cells and secondary stories. Text replacement within one paragraph and selected character formatting preserve surrounding fields, comments, bookmarks, drawings and unbound controls. Selected generated fields, locked or bound controls and tracked runs reject atomically. Structural operations such as splitting or joining still reject paragraphs containing these structures. Splitting or joining section boundaries and joining across cells or stories also reject. Such content remains preserved elsewhere in the document.
+
+The [Word interoperability evidence](../spec/features/word-interoperability.md) covers reviewed agreements, completed forms and generated invoices through actual Word edit/save/reopen journeys. It does not imply compatibility with every Word feature. For paragraph styles without primary names, rendering follows LibreOffice recovery and can omit direct paragraph formatting that Word retains; saved unedited source preserves those properties.
+
+Node and browser documents expose `edit`; server documents forward the same operation. Parsing, semantic construction and browser layout finish before publication, so cancellation or failure leaves the previous document usable. This first implementation rebuilds the document for structural edits. Browser resources stay with the document lifetime, and the sample keeps undo history as document snapshots. Large documents need further editing-performance work before this can serve as a general-purpose editor.
+
+## Embed the Word editor
+
+```js
+import { createEditor } from "@onodocs/sdk/editor";
+
+const editor = createEditor({ container: document.querySelector("#editor") });
+await editor.newDocument();
+const bytes = await editor.save();
+editor.dispose();
+```
+
+The component includes file opening, a new-document command, formatting, imported paragraph styles, lists, regular tables, paragraph images, links, page settings, default headers and footers, find/replace, clipboard operations, undo/redo and Word/PDF downloads. It runs in the browser. `examples/browser-editor/` is the standalone application; run `npm run example:editor` from the source workspace.
+
+Customize the toolbar by passing an ordered list of control names, or `false` to supply your own controls. Available names are `open`, `new`, `save`, `pdf`, `undo`, `redo`, `bold`, `italic`, `underline`, `strike`, `font`, `size`, `color`, `alignment`, `style`, `list`, `table`, `tableTools`, `link`, `image`, `imageTools`, `page`, `header`, `footer`, `find` and `replace`. `fonts` supplies font-family choices; `styles` supplies `{ id, label }` choices using existing Word style IDs. `commands` adds `{ id, label, execute(editor) }` actions. `onChange` receives the editor after committed changes; `onError` reports queued operation failures. Use `document` for browser SDK options such as licensing and font sources, and `readOnly: true` to disable authoring.
+
+The editor supports native text selection and IME input. F6 switches between the document and toolbar, Escape focuses the toolbar, and Shift+Tab leaves the editing area. On touch screens, tap to place the caret, hold to select a word, and drag the selection endpoints. Narrow toolbars scroll horizontally. Mounted pages expose text and headings to browser accessibility tools, including pages whose canvases have been evicted.
+
+Each instance has isolated styles and history. Customize `--onodocs-color`, `--onodocs-background`, `--onodocs-toolbar-background`, `--onodocs-accent` and `--onodocs-selection` on the host container. The `toolbar`, `pages` and `status` shadow parts are available for host styling. Call `dispose()` when removing an editor.
+
+For application controls, use `editor.execute(command)` without a selection field, `editor.select(selection)`, `editor.find(text)`, `editor.replaceAll(text, replacement)`, `editor.undo()`, `editor.redo()`, `editor.save()` and `editor.pdf()`. The current browser document and logical selection are available as `editor.document` and `editor.selection`. Direct document mutations bypass component history; use `execute` for edits that need undo.
+
+The additional SDK `doc.edit` commands use the same selection contract:
+
+| Kind | Arguments | Behavior |
+| --- | --- | --- |
+| `style` | `style: string \| null` | Apply a Word paragraph style ID or remove the direct style |
+| `link` | `target: string \| null` | Link selected text to HTTP, HTTPS, mailto or `#bookmark`; null removes links |
+| `list` | `list: "bullet" \| "decimal" \| null`, optional `level` 0-8 | Set paragraph numbering or remove it |
+| `insertTable` | `rows`, `columns` | Insert a regular table after the selected paragraph |
+| `table` | `action` | `insertRow`, `deleteRow`, `insertColumn`, `deleteColumn` or `delete` |
+| `image` | `bytes`, `mediaType`, `width`, `height`, optional `description` | Insert a PNG/JPEG picture paragraph after the selected paragraph; dimensions are points |
+| `page` | optional `width`, `height`, `margins: { top, right, bottom, left }` | Change the selected section using point dimensions |
+| `header`, `footer` | `text` | Set default story text for the selected section |
+
+The authoring profile supports regular unmerged tables and paragraph-image insertion. Select inline images with `doc.query.images()` and use `imageProperties` with `imageId`, optional point dimensions `width`/`height`, or `remove: true`. The component offers these commands through Image properties after clicking a picture. Floating-image manipulation and merged-table restructuring are not included. Configure review to author tracked text replacements and formatting. Clipboard copy, cut and paste preserve common text formatting, links, paragraph alignment and nested bullet/decimal lists. Tables and image alternative text paste as text, with a conversion message. External stylesheets and custom list formats are not imported. Plain-text clipboard content remains supported. History uses full document snapshots. Structural edits reimport and lay out the candidate document; ordinary typing reuses unchanged semantic data and font measurements. Run `npm run validate:editor` for the component and standalone browser journeys.
+
+## Render and attach ordinary DOM
+
+Mounted views include read-only text selection and plain-text copying. Drag or Shift-click to select text, extend with Shift and the arrow/Home/End keys, select all with Ctrl/Command+A, and copy with Ctrl/Command+C or the Copy context menu. Selection spans pages and survives scrolling and zoom, including pages whose canvases have been released. Document updates clear the previous selection. Attached inputs retain their normal editing and clipboard behavior.
+
+```ts
+import { openDocument } from "@onodocs/sdk/browser";
+import { createDocument } from "@onodocs/canvas";
+
+const doc = await openDocument(file);
+const canvasDocument = createDocument(doc);
+const view = canvasDocument.mount(container);
+const field = doc.query.contentControls().where({ tag: "customer-name" }).one();
+const input = document.createElement("input");
+input.name = "customerName";
+const attachment = view.attach(input, { anchor: doc.geometry.fragments(field)[0] });
+```
+
+The example requires a tagged control that produces one visible fragment. Call `doc.geometry.fragments(field)` for content spanning lines, pages, or repeated stories, and attach to an explicitly chosen fragment. Fragments retain transforms and clipping. Table/cell anchors use their final physical rectangles. `offset` and `size` optionally adjust attachment placement in page units. Values, validation, submission, focus, and accessibility labels belong to the application. Attaching an element moves it into the view. Detachment removes it and restores its original inline style. Reattaching the same HTML element disposes its previous attachment; old handles become inert. An attachment exposes its disposed state.
+
+Pages are anchors too. Placement avoids manual rectangle arithmetic:
+
+```js
+view.attach(checkbox, { anchor: doc.geometry.fragments(doc.query.findText("Client approval:").one())[0], placement: "outside-right", gap: 80, size: { width: 420, height: 420 } });
+view.attach(submitButton, { anchor: doc.pages[0], placement: "inside-bottom-right", inset: 480, size: { width: 2400, height: 600 } });
+```
+
+Inside placements use `inside-{top|center|bottom}-{left|center|right}` with optional `inset`. Outside placements use `outside-{top|right|bottom|left}` with optional `gap` and center the element along the selected edge. The default is `overlay`. All sizes, spacing and offsets use twips (1/1440 inch). Without a size, the element fills the anchor, reduced by the inset for inside placement. Offsets apply after placement. Content anchors retain their transforms and clips; page anchors use the full page. Attachments do not reflow text, so reserve room in the document.
+
+Adjacent styled runs on one line share a fragment. Fragment bounds enclose the unclipped geometry; the supplied clips determine which portions are visible.
+
+`view.setZoom("fit-width")` tracks container width. Numeric zoom uses 96 CSS pixels per inch at `1`. `view.toClient(pageIndex, point)` and `view.fromClient({ x: event.clientX, y: event.clientY })` translate coordinates. `view.hitTest(clientPoint)` returns `{ elementId, fragment, caret? }`. Resolve `elementId` with `doc.query.get(elementId)` when the processing SDK is available. Text hits resolve to a run or paragraph; table whitespace resolves to a cell or table. `caret` contains `{ paragraphId, offset, point }`, with the same UTF-16 offset convention as search ranges. Generated field text omits a caret when no source position can be represented. Raster drawings without a semantic hit identity and blank page space return no element.
+
+`view.scrollTo(anchor, { block: "center" })` reveals a page or a physical fragment. Resolve elements and text ranges through `doc.geometry.fragments(anchor)` first, then choose the occurrence to reveal.
+
+A run's optional `link` is `{ kind: "external", target, tooltip }` or `{ kind: "bookmark", target }`. Use bookmark queries and scrollTo for internal links. The host application decides whether and how to open external destinations.
+
+All page and query indices are **zero based**. Page geometry uses **twips: 1440 units per inch**. `await canvasDocument.pages[index].render(canvas, { dpi: 144 })` prepares the page resources and paints the canvas; `await doc.pages[index].load(signal)` returns the immutable page commands and their resources. Containers should have a usable width. Multiple views can share one document.
+
+Call `attachment.dispose()`, `view.dispose()`, `canvasDocument.dispose()`, or `doc.dispose()` when done. Canvas disposal removes its views and releases its font registrations. Processing disposal also disposes subscribed Canvas documents and releases processing resources. Models remain inspectable; further painting is rejected. Pass `{ signal }` when opening. Opening copies byte inputs; a File/Blob is read once by either the browser or analysis entry point. Fetch URLs in host code with the authentication policy your application needs, then pass bytes.
+
+## Show pages while processing
+
+Progress events expose a document source that the Canvas package can observe. Create the view once. Its subscription follows provisional page replacements and the completed layout.
+
+```ts
+import { openDocument } from "@onodocs/sdk/browser";
+import { createDocument, type CanvasDocument } from "@onodocs/canvas";
+
+let canvasDocument: CanvasDocument | undefined;
+const doc = await openDocument(bytes, {
+  signal,
+  onProgress(progress) {
+    canvasDocument ??= createDocument(progress.document, { container });
+    status.textContent = progress.stage;
+  },
+});
+```
+
+Cancelling or failing processing disposes the source and its subscribed view. After success, dispose `doc` when the application closes the document. A Canvas document can be disposed earlier without closing the processor.
+
+## Render on the server
+
+```ts
+import { readFile, writeFile } from "node:fs/promises";
+import { createRenderer } from "@onodocs/sdk/server";
+
+const renderer = await createRenderer({ channel: "chrome" });
+try {
+  const doc = await renderer.openDocument(await readFile("invoice.docx"));
+  try {
+    await writeFile("invoice.png", await doc.renderPage(0, { dpi: 144 }));
+    await writeFile("invoice.pdf", await doc.pdf({ dpi: 150 }));
+  } finally { await doc.dispose(); }
+} finally { await renderer.dispose(); }
+```
+
+Install Chromium/Chrome separately; use `executablePath` for a deployment-managed binary or `channel: "chrome"`/`"msedge"` for an installed browser. The renderer reuses one browser, with a separate context per document. PNG and JPEG output use the browser engine's Canvas path. PDF preserves document page sizes, including mixed sizes, and includes searchable/selectable Unicode text and external and internal links. Supported solid graphics remain vector content. Native text and complex effects use cropped lossless browser-rendered layers at the requested DPI. The shared browser/server exporter includes tagged headings, lists, tables with merged-cell spans, authored figure descriptions and links. PDF/UA and PDF/A conformance are not claimed.
+
+Contexts make no outbound network requests. Supply fonts as data URLs through `fonts`, or install them on the rendering host. Browser consumers can also supply font URLs. Embedded document fonts use the engine's existing resource path. Use identical browser versions and fonts when reproducible output matters.
+
+Opening and output methods accept an AbortSignal. Cancelling an active operation closes that document context; open a new document to retry. Cancelling an operation still waiting in the queue leaves the active operation and document intact. Both server documents and renderers expose `disposed`. Disposing the renderer closes all remaining documents. A renderer can open multiple documents concurrently; output requests on one document are serialized. Applications control scheduling and process isolation.
+
+## Process on the backend and render in the frontend
+
+The [complete backend viewer sample](https://github.com/onodocs/onodocs/tree/main/examples/backend-viewer) includes a Node.js server, working endpoints, a browser frontend and an authored DOCX. Install Node.js 22.18 or newer and Google Chrome, then run:
+
+```sh
+git clone https://github.com/onodocs/onodocs.git
+cd onodocs/examples/backend-viewer
+npm install
+npm start
+```
+
+Open http://127.0.0.1:5175. Use `npm start -- /path/to/document.docx` to open another server-side file. Stop the server with Ctrl+C. The [website guide](https://onodocs.com/developers/#combined) includes the complete server and frontend source.
+
+The server's `manifest({ format: "json" })` and `page(index, { format: "json" })` methods return response bodies ready to send with `Content-Type: application/json`. For a document at `/document`, serve its manifest there and individual pages at `/document/pages/:index`. The original methods without a format option still return typed objects for in-process use.
+
+```js
+import { openDocument } from "@onodocs/canvas";
+
+const doc = await openDocument("/document", {
+  container: document.querySelector("#pages"),
+  viewOptions: { zoom: "fit-width" }
+});
+await doc.view.whenRendered();
+```
+
+Canvas handles loading and decoding. It requests page content as needed. `signal` cancels requests; `request` accepts fetch options such as `headers` and `credentials` for both the manifest and page requests. Same-origin cookies work by default. Requests default to no-store, and non-successful HTTP responses reject with the status code. Dispose the Canvas document when closing or replacing the view.
+
+The application owns the endpoints and document authorization. Keep server documents open while their endpoints are in use, then dispose them. For updates, publish each completed snapshot at its own URL and reopen the frontend view. Use matching SDK and Canvas releases.
+
+Selection, copying, hit testing, zoom and attachments use the published geometry. Queries and updates stay on the backend. The frontend receives the visible text and resources needed to display the document. Supplied and embedded fonts travel with the pages; fonts resolved from the server's installed fonts must also be available on the client.
+
+## Errors and application data
+
+Opening, updating, and exporting can reject. Handle errors at your application boundary and dispose browser/server resources in finally blocks. The analysis and browser entries export `PackageOperationError`, `SemanticOperationError`, and `QueryCardinalityError`; cancellation uses the signal's reason.
+
+Query elements are readonly in-memory models with parent references, source metadata, and bigint values. Project the fields your application needs instead of serializing the entire model:
+
+```ts
+const paragraphs = doc.query.stories().where({ story: "body" }).paragraphs()
+  .map(({ id, text, style }) => ({ id, text, style }));
+const json = JSON.stringify(paragraphs);
+```
+
+The same projection supports AI context, search indexing, and backend messages without coupling your data format to engine internals.
+
+## Low-level stages
+
+`doc.source` is the typed source model and `doc.semantic` contains completed document meaning. Element `source` locations refer into `doc.source.sourceFacts` and provenance. These identifiers belong to that loaded document, not arbitrary later revisions. The models describe supported DOCX content; they do not preserve every XML detail for round-trip writing.
+
+The main SDK also exports the core stage APIs: `parseDocumentSource`, `createSemanticDocument`, `parseDocumentForRendering`, font preparation, `createLayoutDocument`, and `createPageDisplayList`. Low-level `materializePageDisplayListToCanvas` is exported by `@onodocs/canvas`. Advanced consumers can stop at a stage or replay paint through their own adapter. Use canonical readonly contracts; do not mutate stage outputs. Layout remains the authority for all physical geometry.
+
+### Extract a table as text
+
+```ts
+const data = doc.query.tables()
+  .where({ headers: ["Deliverable", "Owner", "Due"] })
+  .one().textRows;
+```
+
+`textRows` includes the first row and keeps cells grouped by their own table rows. The header filter matches the first row exactly, in order and case sensitively; it does not infer header formatting. Nested tables remain text inside their containing cells. Merged cells retain authored topology; the result is not padded into a rectangular grid. Use `data.slice(1)` to omit the header. The readonly matrix is a snapshot; query again after an update.
+
+## Large documents
+
+Use the progress subscription shown above to display early pages while layout continues. Early pages are provisional: page counts, fields, notes and placement can change as formatting settles. Opening resolves with the complete document. Abort the loading signal to dispose the source and its subscribed views.
+
+Mounted views paint the visible neighborhood and release distant canvas pixels. Zoom and scrolling render pages on demand. Decoded images are acquired only for a page render and released afterward. Parsing and document layout still require memory proportional to document content; virtualization does not make the document model constant-memory. Auto-fit tables and document-wide fields can require later content before their output settles.
+
+Await page renders before reading or exporting the canvas:
+
+```js
+await canvasDocument.pages[0].render(canvas, { dpi: 144, signal: controller.signal });
+const png = canvas.toDataURL("image/png");
+```
+
+For documents that omit font declarations, browser and server opening options accept `defaultFont` and `defaultFontSize` (points). They default to Calibri and 11pt; authored font choices and sizes take precedence.
+
+## Review and saved versions
+
+Node and browser documents expose the same review operations. Supply your application's user identity and timestamp for authored comments and changes:
+
+```js
+const identity = { author: currentUser.name, initials: currentUser.initials, date: new Date().toISOString() };
+const paragraph = doc.query.paragraphs().first();
+const selection = { start: { paragraphId: paragraph.id, offset: 0 }, end: { paragraphId: paragraph.id, offset: 6 } };
+await doc.review({ kind: "comment", selection, text: "Please verify this wording.", identity });
+const thread = (await doc.readReview()).comments.at(-1);
+await doc.review({ kind: "reply", id: thread.id, text: "Confirmed.", identity });
+await doc.review({ kind: "resolveComment", id: thread.id, resolved: true });
+await doc.review({ kind: "trackedReplace", selection: thread.selection, text: "Revised", identity });
+await doc.review({ kind: "revision", accept: true });
+const bytes = await doc.save();
+```
+
+Open with `revisionView: "accepted"` when editing current text. `readReview()` includes hidden deleted changes, which may have no visible selection. Pass revision `ids` to accept or reject individual changes; omit them for all changes. `trackedFormat` records selected run formatting with a rejectable property snapshot. `trackChanges` enables or disables Word's tracking setting. Review mutations support `signal` and `ifUnchangedSince` like ordinary edits. Text replacement stays within a paragraph; comments can span paragraphs in one story. Protected documents retain their write restrictions.
+
+Enable the editor panel with `review: { identity: () => identity, history }`. The optional `history` object implements `list(signal)`, `load(id, signal)` and `save(version, bytes, signal)`. Your application stores the complete Word bytes and version metadata. The SDK adds no persistence service or user account system. Restoring a version is undoable and raises the editor's change event, so application autosave can persist it. `compareDocuments(savedBytes, doc)` returns paragraph text and formatting differences without modifying the document.
+
+## Searchable PDF in the browser
+
+```js
+import { openDocument } from "@onodocs/sdk/browser";
+
+const doc = await openDocument(await file.arrayBuffer());
+try {
+  const bytes = await doc.pdf({ dpi: 150, title: "Quarterly report", language: "en-US" });
+  const url = URL.createObjectURL(new Blob([bytes], { type: "application/pdf" }));
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = "document.pdf";
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+} finally {
+  doc.dispose();
+}
+```
+
+PDF export runs locally and uses the same implementation as server `doc.pdf()`. It waits for earlier edits to finish. Pass `signal` to cancel an export without closing the document. The PDF writer loads on demand; deploy the browser entry's generated chunks alongside it. Text extraction order for bidirectional paragraphs and selection across complex clusters depend on the PDF reader. Solid graphics use vector PDF paths where supported. Native text and complex effects retain browser rendering in cropped lossless image layers, including evaluation marks. Higher DPI increases the sharpness, file size and temporary memory use of those layers; compressed output remains in memory until export finishes.
+
+The PDF includes tagged headings, paragraphs, nested lists, tables, header cells, merged-cell row/column spans, authored figure descriptions and links, plus heading and bookmark navigation. Set `title` and `language` for reader metadata. DrawingML descriptions use `wp:docPr/@descr`, falling back to `title`; VML uses authored `alt` text. Undescribed graphics remain artifacts. Reader support varies. Firefox PDF.js exposes named images, list nesting and table spans in its accessibility tree. This does not claim PDF/UA conformance or validation with every screen reader.