@onodocs/canvas 0.2.0 → 0.3.0

package/README.md

@@ -1,229 +1,281 @@
-# 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:
+# 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`, `pdf`, or `save`. Exports reflect the updated text.
+
+## Save an edited Word document
+
+`save()` returns DOCX bytes in Node, the browser, and server rendering. Saving without edits returns the original file 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.
+
+```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, enabled change tracking, macro-enabled documents and templates can be saved unchanged, but editing them is not supported. Field recalculation and revision authoring are not included. Field caches remain as imported, and saved bookmark/comment markers retain their original run boundaries. 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
-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 server renderer publishes a manifest with page sizes and interaction data. Its `page(index)` method returns the same `PageDisplayList` used by local Canvas rendering. Expose these results through authenticated routes in your application. The package does not install an HTTP server or choose an authentication policy.
-
-```ts
-import { createRenderer } from "@onodocs/sdk/server";
-import { encode } from "@onodocs/canvas";
-
-const renderer = await createRenderer({ channel: "chrome" });
-const doc = await renderer.openDocument(bytes, { fonts });
-
-const manifestResponse = encode(await doc.manifest());
-const firstPageResponse = encode(await doc.page(0));
-```
-
-Use `encode` and `decode` for HTTP bodies because page geometry contains bigint coordinates and resources contain byte arrays. They encode the canonical contracts directly. The transport has no separate document model or schema version. Both packages should come from the same release.
-
-The frontend imports only the Canvas package. This example expects `/document/manifest` and `/document/pages/:index` routes supplied by the application:
-
-```ts
-import { createDocument, decode, type DocumentManifest, type PageDisplayList } from "@onodocs/canvas";
-
-const response = await fetch("/document/manifest");
-if (!response.ok) throw new Error("Document is unavailable.");
-const manifest = decode<DocumentManifest>(await response.text());
-const canvasDocument = createDocument({
-  pages: manifest.pages.map(page => ({
-    ...page,
-    async load(signal) {
-      const response = await fetch(`/document/pages/${page.index}`, { signal });
-      if (!response.ok) throw new Error("Page is unavailable.");
-      return decode<PageDisplayList>(await response.text());
-    },
-  })),
-}, { container });
+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();
 ```
 
-Selection, copying, hit testing, zoom and attachments work from the published geometry. Semantic queries and updates remain on the backend. After an update, publish a fresh manifest and page set; do not mix pages from different document snapshots. Applications can cache immutable page responses or share resource transfers to suit their transport. Dispose the Canvas document when replacing its source, and dispose server documents and the renderer when they are no longer needed.
-
-Published pages contain visible text and resources. Keeping the source DOCX on the backend does not hide the displayed content from the frontend. Supplied and embedded font bytes travel with the pages. Fonts resolved from the server's installed fonts remain explicit local font declarations and require the same fonts on the client; supply font files for deployment across different hosts. Backend image/PDF export remains available when a client cannot reproduce the required font environment.
-
-## 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");
-```
+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. Operations affecting paragraphs with fields, links, controls, drawings, comments, bookmarks, tracked revisions or unsupported children reject atomically. Splitting or joining section boundaries and joining across cells or stories also reject. Such content remains preserved elsewhere in the document. The narrower `update()` operation continues to support safe text replacement within unbound controls.
+
+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.
+
+## Run the inline browser editor sample
+
+From the source workspace, run `npm run build` and `npm run example:editor`, then open `http://127.0.0.1:5190`. The sample opens its included Word document and accepts local DOCX files. Click directly on a rendered page to type, drag to select text, and use the toolbar to change formatting. Enter splits paragraphs; Backspace at a paragraph's start joins it to the previous paragraph. Shift+Enter inserts a line break. The sample also supports keyboard selection, copy/cut, plain-text paste, undo/redo and Word download. Files remain in the browser.
+
+The sample is in `examples/browser-editor/`. It consumes only exported SDK and Canvas APIs. Canvas `createDocument` accepts a native textarea through `viewOptions.input`, plus an `onSelectionChange` callback in the same options. The view positions this input at the published caret, handles selection using layout geometry, and exposes `selection` and `setSelection`. The application handles input events and submits `doc.edit()` operations. Text, line wrapping and pagination remain rendered by OnoDocs.
+
+Run `npm run validate:editor` for the browser editing journey. The sample currently uses the workspace build; it requires the new editing APIs and does not work against the earlier published package.
+
+## 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");
+```