@betteroffice/docx 0.4.3 → 0.5.0

package/README.md

@@ -1,654 +1,164 @@
 # @betteroffice/docx
 
-Framework-free core for the BetterOffice DOCX editor — the Rust engine (OOXML
-parse/serialize, CRDT editing core, text shaping, pagination) compiled to
-WebAssembly, plus the display-list, canvas-render, geometry, and accessibility
-helpers the adapters build on. Layout never touches the DOM: the engine
-measures every line and pages are replayed onto canvas.
+Framework-free DOCX parsing, serialization, CRDT editing, layout, and canvas rendering backed by
+Rust/WebAssembly. Use it for document processing or a custom editor adapter.
+
+## Install
 
 ```bash
 bun add @betteroffice/docx
 ```
 
-Most apps want the turnkey React component in
-[`@betteroffice/docx-react`](https://www.npmjs.com/package/@betteroffice/docx-react).
-Reach for this package directly for headless parsing/serialization or when
-building a custom adapter.
+`@betteroffice/fonts` is an optional peer dependency for font assets.
 
-## Parse and save
+## Usage
 
-A full round trip: open a `.docx`, inspect the typed model, write bytes back.
+Parse a DOCX and save it while preserving untouched package parts:
 
 ```ts
 import { readFile, writeFile } from 'node:fs/promises';
-import { parseDocx, repackDocx } from '@betteroffice/docx/docx';
+import { parseDocx, repackDocx } from '@betteroffice/docx';
 
-const document = await parseDocx(await readFile('contract.docx'));
+const document = await parseDocx(await readFile('input.docx'));
 // document.package.document.content: the body's paragraphs and tables
 // document.package also holds styles, numbering, theme, media, headers and footers
-
 const bytes = await repackDocx(document);
-await writeFile('contract-out.docx', Buffer.from(bytes));
+await writeFile('output.docx', new Uint8Array(bytes));
 ```
 
-`repackDocx` round-trips against the original buffer so untouched parts are
-preserved; use `createDocx` for documents built from scratch.
+## Entry points
 
-The engine ships as four wasm assets (container, parser, layout, editing core)
-in `dist/generated/`. Browsers fetch them lazily behind the async entry points
-(`parseDocx`, save, the layout engine, `createYrsSession`); Node and Bun read
-them from disk synchronously on first use. No manual init call is required.
+| entry point | description |
+| --- | --- |
+| `parseDocx` | Read an `ArrayBuffer`, `Uint8Array`, `Blob`, or `File` into a document model. |
+| `repackDocx`, `repackDocxWithWarnings` | Save a parsed model against its original package; the latter also returns save warnings. |
+| `createDocx` | Write a new document model without an original package. |
+| `createYrsSession` (from `@betteroffice/docx/yrs`) | Asynchronously create a CRDT editing session. |
+| `saveYrsDocx` (from `@betteroffice/docx/yrs`) | Save a session opened from DOCX bytes, returning bytes and persisted paragraph anchors. |
 
-## Collaboration
+For a React editor and viewer, use
+[`@betteroffice/docx-react`](https://www.npmjs.com/package/@betteroffice/docx-react).
 
-Connect the editor's Yrs replica to any reliable binary transport:
+## Runtime and assets
 
-```ts
-import { CollaborationProvider } from '@betteroffice/docx/collaboration';
+The package ships container, parser, layout, and editing WebAssembly assets in `dist/generated/`.
+Async entry points load the assets they need; no manual initialization is required for parsing or
+creating a session. Preserve the packaged asset URLs when bundling for a browser.
 
-const provider = new CollaborationProvider(replica, createTransport(), {
-  user: { name: "Ada" }, // identity for this peer's remote caret
-});
-provider.connect();
-```
+Core sessions expose synchronous editing and read methods after asynchronous creation. The React
+editor runs its engine in a Web Worker by default and exposes promise-returning document reads,
+edits, and exports. Release a direct session with `session.destroy()` when finished.
 
-`replica` can be a direct `YrsSession`, the worker-aware adapter returned by
-`createWorkerCollaborationReplica`, or the value published by the React
-editor's `collaboration.onReplica` callback. The provider handles Yjs sync-v1 and
-awareness; room routing, authentication, and reconnection remain transport
-concerns. Pass a persisted Yrs update as `collaboration.initialUpdate`
-when a React editor joins an existing room so it hydrates the shared history
-instead of independently importing the same DOCX.
+## Undo grouping
 
-## Development
+A story is one text flow: the body, a header or footer, a footnote, or a comment.
+`session.setUndoCaptureMode(mode)` selects how local transactions group into undo steps;
+`session.undoCaptureMode()` reads the mode. Call `session.beginUndoCapture()` after import or seeding.
 
-The generated `.wasm` binaries are intentionally not committed. From the
-repository root, install `wasm-pack` 0.15.0 and `binaryen`, then run
-`bun run build:docx-wasm`.
-Package builds, demo startup, and CI run this step automatically.
+| Mode | Grouping |
+| --- | --- |
+| `auto` (default) | Nearby edits coalesce; switching stories closes the group. |
+| `manual` | Edits coalesce until an explicit boundary, including across stories. |
 
-[JavaScript guide](https://docs.betteroffice.dev/docs/javascript) ·
-[Changelog](https://github.com/openooxml/betteroffice/blob/main/packages/docx/CHANGELOG.md) · Apache-2.0.
+`session.addUndoBoundary()` closes the current group. Changing modes also closes it while keeping
+history; setting the same mode does not. In manual mode, close groups before unrelated edits.
+Remote transactions stay outside local undo history; edit batches supply atomic execution.
 
-### Undo capture modes and boundaries
+## Selection state
 
-`session.setUndoCaptureMode(mode)` selects how tracked local transactions are
-combined into undo steps. `session.undoCaptureMode()` returns the current mode.
+`session.selectionContext(range)` aggregates formatting across a paragraph-addressed selection.
+Toggle formatting is `true`, `false`, or `'mixed'`; value formatting is `null` when absent or
+nonuniform. Use this state to drive custom formatting controls.
 
-| Mode | Grouping |
-| --- | --- |
-| `auto` (default) | Edits within 500 ms coalesce; switching stories closes the group. |
-| `manual` | Edits coalesce across pauses and stories until an explicit boundary. |
+## Host proposals
 
-`session.addUndoBoundary()` closes the current group in any mode. Changing modes
-also closes the group; setting the same mode again does not. Both operations
-preserve undo/redo history and are safe before capture starts. Repeated boundaries
-create no empty undo steps. Remote transactions remain outside local undo history.
+`session.proposeChanges({ expectVersion, proposals })` applies a version-checked round of tracked
+changes grouped by host proposal IDs, outside undo history. Each proposal names its `id`, target
+`paragraph`, an `op` (`replaceText` or `insertText`) and `suggest: { author, date }` for attribution.
+A refusal leaves the round unapplied.
 
-```ts
-session.setUndoCaptureMode('manual');
-session.insertText(firstLocation, 'Prefixo ');
-session.insertText(secondLocation, 'Suffix');
-session.addUndoBoundary();
-session.deleteRange(markerRange);
-session.addUndoBoundary();
-session.setUndoCaptureMode('auto');
-```
+`session.setProposalStates({ expectVersion, expectPreviewVersion, changes })` changes how proposals
+preview without changing the document or undo history. `session.withdrawProposals({ expectVersion,
+ids })` settles accepted proposals as plain text and removes rejected or undecided ones, so later
+rounds search the text shown by the preview.
 
-The two insertions undo together; marker deletion is a separate step. Boundaries
-are also available in automatic mode when a host action needs to be isolated from
-surrounding typing. Undo/redo close capture as usual. Manual mode groups history;
-edit batches provide atomic execution.
-The host must close manual groups so later unrelated edits do not join them.
+Read the registry with `session.getProposals()` or observe it with `session.onProposalChange()`.
+Opening another document clears the registry. Use `proposalRevisionPreview(snapshot)` from
+`@betteroffice/docx/yrs` as the layout render environment's `revisionPreview` to display decisions.
 
-### Paragraph identities
+## Comment ranges
 
-A session addresses paragraphs by session keys (`YrsLoc.paraId`); Word stores its
-own paragraph ID (`w14:paraId`) in the file. A session anchor resolves on every
-replica of one collaborative session, and each seeding open (`openDocx`, `seedFromDocx`, `documentToYrs`) starts a new one unless given a fixed
-`generation`, as a deterministic shared seed needs. Source IDs are kept as authored, and every
-paragraph authored in the session gets a fresh, valid ID that avoids every ID the
-package already uses.
+`session.setCommentRanges(commentId, ranges)` replaces an existing comment's sticky anchors while
+preserving its metadata. Ranges may span paragraphs or address separate stories; each must be
+nonempty, ordered, and within existing paragraphs. Invalid input throws before changing the comment.
 
-`saveYrsDocx(session)` saves a session opened from DOCX bytes and returns each saved
-paragraph's persisted anchor, qualified by its package part:
+Reanchoring joins local undo capture. `saveYrsDocx(session)` writes the current ranges; a host that
+removes all commented text must choose a surviving range or remove the comment.
 
-```ts
-import { createYrsSession, saveYrsDocx } from '@betteroffice/docx/yrs';
+## Edit batches
 
-const { secondParaId } = session.splitParagraph({ story: 'body', paraId, offset: 12 });
-const saved = await saveYrsDocx(session);
-const anchor = saved.paragraphs.find((p) => p.session.paraId === secondParaId)!.persisted;
+Read targets with their session version, then apply all steps atomically against that version.
+See [version-checked DOCX batches](https://docs.betteroffice.dev/docs/javascript#edit-docx-in-version-checked-batches)
+for operations, offsets, limits, and typed refusals.
 
-const reopened = await createYrsSession();
-reopened.openDocx(saved.bytes, true);
-reopened.resolveParagraphAnchor(anchor); // { status: 'found', anchor: { kind: 'session', … } }
-```
+## Paragraph anchors
 
-`saved.conflicts` lists saved paragraphs whose ID the live session reassigned while the
-save ran, such as by a duplicate repair after a remote update; their anchors find them in
-the saved bytes only. The React editor's Save writes and records these IDs. `saveYrsDocx`
-also returns anchors and preserves unchanged source parts. `session.persistParagraphIds()`
-assigns IDs to source paragraphs without one across every story part, comments,
-note separators and retained XML included, and repairs duplicates: source IDs and
-saved IDs keep theirs over copies. It refuses, changing nothing, rather than guess at
-an ambiguous comment reference. The change is replicated, stays out of undo history,
-and later saves keep it; a save whose stories are otherwise unchanged patches the IDs
-into the source bytes. `session.paragraphIdentities()` lists each paragraph's session,
-persisted and exact-source anchors. A persisted anchor is scoped to the document the
-host chose, and repeated source IDs resolve as `ambiguous`.
-
-### Selection state
-
-`session.selectionContext(range)` aggregates the range for toolbars and
-assistive technology. Toggle marks, including `superscript` and `subscript`,
-are `true`, `false` or `'mixed'`; value marks such as `fontFamily`, `color` and
-`highlight` are `null` when absent or not uniform. `highlight` reports Word's
-highlight name (`'yellow'`) or an unmapped hex value. `toggleMark` accepts
-`{ type: 'superscript' }` and `{ type: 'subscript' }`; adding one clears the other.
-
-### Version-checked edit batches
-
-Read what you will target together with the session version, then apply a batch
-against that version. Every step resolves against the state that was read; the
-batch commits as one transaction or returns a typed refusal with nothing changed.
+Session paragraph keys identify paragraphs within a collaborative session; persisted anchors identify
+saved paragraphs by package part and OOXML paragraph ID. See
+[DOCX paragraph anchors](https://docs.betteroffice.dev/docs/javascript#docx-paragraph-anchors)
+for saving, reopening, resolving, and assigning IDs.
 
-```ts
-const read = session.readParagraphs({ story: 'body', view: 'accepted' });
-if (!read.ok) throw new Error(read.failure.message);
-const clause = read.paragraphs.find((paragraph) => paragraph.text.startsWith('Term'))!;
-
-const result = session.applyEdits({
-  expectVersion: read.version,
-  steps: [
-    {
-      op: 'replaceText',
-      target: { kind: 'search', text: '30 days', view: 'accepted',
-        within: { kind: 'paragraph', story: 'body', paraId: clause.paraId } },
-      text: '45 days',
-      expect: { text: '30 days' },
-    },
-    {
-      op: 'insertParagraphs',
-      target: { story: 'body', paraId: clause.paraId },
-      at: 'end',
-      paragraphs: [{ text: 'Renewal is automatic.' }],
-    },
-  ],
-});
-if (!result.ok) console.warn(result.failure.code, result.failure.message);
-```
+## Structured export
 
-`version()` changes with every committed change, local or remote (including
-undo and redo), and when the session reopens its document. Tokens are scoped to
-one session; after a lost response, read again rather than retrying with a new
-version.
+For `exportDocxStructured` and `exportDocxMarkdown`, see
+[structured content](https://docs.betteroffice.dev/docs/javascript#export-docx-as-structured-content)
+for anchored JSON or Markdown, revision views, story selection, and live-session exports.
 
-Offsets are UTF-16 positions into a paragraph's projected text. Each inline atom
-(hard break, image, content control, note reference, field, other embed) is one
-U+FFFC listed in `atoms`, tabs stay `\t`, and paragraph marks are excluded. The
-`accepted` view includes pending insertions and hides pending deletions;
-`original` does the reverse. `findText` is exact, case-sensitive and
-paragraph-local, and a `search` target must match exactly once in its scope.
+For `exportDocxStructuredWithPages`, see
+[page fragments](https://docs.betteroffice.dev/docs/javascript#page-fragments) for font requirements,
+layout maps, and page geometry.
 
-| Step | Effect |
-| --- | --- |
-| `insertText` | Inserts at the start or end of a target, formatted like typing there. |
-| `replaceText` | Replaces a target's text inside one paragraph, keeping the paragraph. |
-| `deleteText` | Deletes a target's text inside one paragraph. |
-| `insertParagraphs` | Inserts complete paragraphs before or after an anchor, in the given or the anchor's style. |
-| `deleteParagraphs` | Deletes a contiguous span of complete paragraphs without merging properties into a neighbour. |
-| `setParagraphStyle` | Applies a document paragraph style with its paragraph and run formatting. |
-
-Refusals carry a `code` (`stale-version`, `missing-target`, `ambiguous-target`,
-`content-mismatch`, `overlapping-steps`, `locked-target`,
-`tracked-revision-conflict`, `unsupported`, `invalid-step`, `limit-exceeded`),
-the failing `stepIndex`, and the target. Editor hosts add `read-only` for an
-editor that does not accept edits. Malformed requests throw.
-`validateEdits(request)` runs the same checks and previews each step without
-changing anything or reserving ids.
-
-An applied batch is exactly one undo step in both capture modes; pass
-`history: 'none'` to keep it out of undo history while preserving existing undo
-and redo entries. `source: 'agent'` records provenance only. Add
-`suggest: { author, date }` to a text step to record it as a tracked change.
-
-Paragraph ids are session keys; inserted paragraphs get Word paragraph IDs as
-typed ones do, so `saveYrsDocx` returns persisted anchors for them.
-
-### Host proposals
-
-`session.proposeChanges()` records a round of reviewable tracked changes under
-the host's own proposal ids. Each proposal names its paragraph by any paragraph
-anchor, such as a persisted Word paragraph ID, and replaces, deletes
-(`replaceWith: ''`) or inserts text:
+Deprecated: `collectHeadings` from `@betteroffice/docx/utils`; use `session.headings(story)` instead.
 
-```ts
-const result = session.proposeChanges({
-  expectVersion: session.version(),
-  proposals: [
-    {
-      id: 'p-17',
-      paragraph: { kind: 'persisted', story: { partUri: '/word/document.xml', kind: 'body' }, paraId: '1A2B3C4D' },
-      suggest: { author: 'Reviewer', date: new Date().toISOString() },
-      op: 'replaceText',
-      search: '30 days',
-      replaceWith: '45 days',
-      occurrence: 'all',
-    },
-  ],
-});
-```
+## Content controls
 
-`occurrence` is `'first'` (the default), `'all'` or a one-based number, counting
-non-overlapping matches of the accepted text. `search: ''` fills an empty
-paragraph: it matches once, at the start of a paragraph whose accepted text is
-empty (hyperlinks, fields, content controls and pending insertions count as
-text), and refuses with `missing-target` anywhere else. Text typed into a
-paragraph without runs takes the paragraph mark's run formatting, as in Word.
-The round applies as one batch
-outside undo history, or nothing changes and a typed refusal names the
-`proposalId`: an ambiguous paragraph ID refuses with `ambiguous-target`, and
-adjoining or overlapping proposals with `overlapping-steps`. Retrying an id with
-the same edit is a no-op; the same id with another edit refuses with
-`proposal-id-conflict`. Each record lists the revision ids its proposal created.
-
-`session.setProposalStates()` marks proposals `accepted`, `rejected` or back to
-`proposed`. Decisions keep the tracked revisions and change only how they render:
-`proposalRevisionPreview(snapshot)` is the `revisionPreview` render environment
-entry that shows accepted proposals as plain text and hides rejected ones. They
-leave the document, its version and undo history untouched, and each change
-increments `previewVersion`, which `expectPreviewVersion` checks
-(`stale-preview`). `getProposals()` and `onProposalChange()` read and observe
-the registry; opening another document forgets it.
-
-`session.withdrawProposals({ expectVersion, ids })` ends proposals the host is
-done with, settling each as its decision previews it: accepted ones apply as
-plain text and rejected or undecided ones are removed, in one change outside
-undo history. The document then reads as the preview did, so the next round's
-searches match the text the reader saw. Ids that name no proposal are ignored.
-
-### Structured export
-
-Export read-only structured JSON or Markdown with block and inline anchors and
-diagnostics.
+`listDocxContentControls` and `findDocxContentControls` inspect controls in DOCX bytes.
+See [content controls](https://docs.betteroffice.dev/docs/javascript#fill-docx-content-controls)
+for session discovery, version-checked fills, and supported control types.
 
-```ts
-import { exportDocxMarkdown, exportDocxStructured } from '@betteroffice/docx';
-
-const content = await exportDocxStructured(bytes, {
-  revisionView: 'accepted',
-  stories: ['body', 'headers', 'footers'],
-});
-for (const block of content.stories[0].blocks) {
-  if (block.kind === 'heading') console.log(block.heading.outlineLevel, block.anchor);
-}
-const { markdown, anchors } = await exportDocxMarkdown(bytes, { revisionView: 'markup' });
-```
+## Compare documents
 
-On a live session, `session.exportStructured(options)` and
-`session.exportMarkdown(options)` return `{ ok: true, version, content }` from one
-read of the committed state: anchors resolve against that version, and nothing is
-committed, flushed or published. Bytes exports and `renderDocxMarkdown(content)`
-return snapshot content and throw `DocxExportError` for unusable options. A
-refusal's `failure` is `{ code, target, message }`, with `target: null` when it
-concerns no anchor; `unsupported` means the session holds no document content.
-`session.headings(story)` lists a story's headings classified the same way; the
-legacy `collectHeadings` tree walker from `@betteroffice/docx/utils` is deprecated
-in its favour.
-
-Content is `schemaVersion: 1`: ordered stories (`body` by default; `headers`,
-`footers`, `footnotes`, `endnotes` and `comments` only when selected), each a list
-of paragraphs, headings (outline level and whether it came from direct formatting,
-the style chain, document defaults or a `HeadingN` style id), list items (numbering
-format and the rendered marker, counted as Word counts them: numbering instances of
-one abstract definition continue each other unless one overrides a start and so
-begins its own list, levels begin at `w:start` and restart as `w:lvlRestart` says),
-tables on the source grid with spans, skipped grid columns and vertical-merge
-continuations, content controls, section breaks, and placeholders naming the
-source element of other content. Inlines cover text, tabs, line,
-page and column breaks where the source has them, note and comment references,
-fields with their cached result in result order, hyperlinks and nested fields
-included, all anchored to the field (a numeric field's result
-blocks stay inside the field), images (alt text and the relationship of the part
-that owns them) and inline controls. A header or footer part
-referenced through several relationships is one story with every section that
-uses it while the copies hold the same content, and one story per copy with a
-diagnostic once they differ. `revisionView` is required: `accepted` and
-`original` project pending revisions like `readParagraphs`, and `markup` keeps
-both with `revisions` attribution on each inline, moves as `moveFrom` and
-`moveTo`. Other revision history exports as an anchored `unsupported`
-placeholder with an `unsupported-revision` diagnostic.
-
-Anchors use the batch offsets and session keys: a paragraph anchor's `paraId` is the
-batch target key, and a range is paragraph-local UTF-16 in the view it
-names, one U+FFFC per atom, the same shape the edit batches take; ranges from a
-session export address the version it returned. Content without a session
-location (comment bodies, omitted raw XML) carries a `sourcePart` anchor: the
-part, its SHA-256, and element-child ordinals into its XML. Content with no
-location of its own carries `{ kind: 'unlocated', story, reason }`: the reason is
-`duplicate-paragraph-id` (a paragraph whose Word paragraph ID repeats an earlier one
-opens with a session key of its own, and edits and merges repair a key two paragraphs
-share, so only shared state written outside the engine has it), `story-too-large`,
-`missing-story` or
-`provenance-unavailable`. Comment metadata reads
-the session's comment store once a field has been written there, and the source
-until then. Ids are deterministic export-tree paths, and a bytes export is
-identical across runs. Exports admit one top-level block at a time, charge text before copying it, and stop at
-`maxBlocks` (10,000 by default, every nested block counted) or `maxBytes`
-(8,388,608 by default, on the compact JSON) at a whole top-level block, set
-`truncated`, and end with a `truncated` diagnostic; the prefix already admitted is
-kept, and a larger `maxBytes` never keeps fewer blocks. Of a story longer than
-four units per remaining byte beyond one million, only the leading paragraphs
-within that bound are read: those that fit are kept, then the export stops and says
-so. A comment body, field payload, shape or table cell past the bound is not read
-at all. Markdown keeps story separators, headings, lists, tables (pipe tables, or
-entity-escaped HTML, nested where needed, for merged or multi-block cells), attributed insertions and deletions, and a
-`<!-- docx-export:N -->` marker per block, nested ones included, mapped to its
-anchor in `anchors`. Only http, https, mailto and internal-anchor targets are linked,
-judged after entity and percent decoding, and `&` in a target is written `&amp;`; document text, titles and alt text never keep a
-line break or unescaped HTML.
-
-### Page fragments
-
-A paged export attaches a page map to the structured content: the physical page,
-section and displayed page label showing each block and inline, and the body,
-header, footer or note occurrence it sits in.
+`compareDocx` compares two DOCX files and returns tracked text changes or diagnostics.
+See [DOCX comparison](https://docs.betteroffice.dev/docs/javascript#compare-docx-files-into-tracked-changes)
+for supported inputs, attribution, and refusal behavior.
 
-```ts
-import { exportDocxStructuredWithPages, renderDocxMarkdownWithPages } from '@betteroffice/docx';
-
-const paged = await exportDocxStructuredWithPages(
-  bytes,
-  { revisionView: 'markup', stories: ['body', 'headers', 'footnotes'], includeGeometry: true },
-  { fonts: [{ key: 'sans', data: fontBase64 }], defaultChain: ['sans'] }
-);
-paged.layout.pages; // pageIndex, displayedLabel, sectionIndex, parityFiller, size
-paged.layout.fragments; // pageIndex, occurrenceId, nodeId, slice, continuation flags, geometry
-const { markdown } = await renderDocxMarkdownWithPages(paged, { pageMarkers: true });
-```
+## Collaboration
 
-`exportDocxStructuredWithPages` opens the bytes in a private session, registers
-exactly the fonts it is given, as base64 data, in a measurement font store of its
-own (a requirement `family|bold|italic` takes the chain named by its key, else by
-its lowercase family, else `defaultChain`; nothing is looked up on the system and
-no editor's fonts change), lays out every section, header, footer and note, and
-exports from that one state. Its options are plain JSON: `measurementDefaults`
-(`fontFamily`, `fontSize`), `renderEnvironment` (`showHiddenText`,
-`defaultTabStopTwips`) and `compatibility`, all fingerprinted in the map's
-provenance. A requirement left with no font, including the `measurementDefaults`
-family text naming none falls back to, or any text measured with stand-in metrics
-is refused as `layout-unavailable`, as is a live layout whose font store was
-cleared or added to since.
-The snapshot map is deterministic for the same bytes, fonts and options and
-carries no session token. `session.exportStructuredWithPages(options)` reads the
-region layout a session retains and lays nothing out, flushes nothing and loads no
-font; the layout must have lowered the current version from the session's own
-stories, with section, settings and note metadata that describe it and a
-registered font for every requirement. Its map carries `documentVersion` and a
-`layoutVersion` to pass back as `expectLayoutVersion`; its references describe the
-authoritative layout of that version, which a later edit may supersede before it is
-painted.
-
-`pageIndex` counts physical pages from zero, blank parity pages included, while
-`displayedNumber`/`displayedLabel` follow the section's PAGE numbering (restarts,
-continuation and Roman or letter formats). A header or footer part stays one exported story with an occurrence
-on every page showing it; a note has an occurrence where its note area is, which
-may differ from its reference's page. Text slices are ranges in the export's own
-offsets, split where the node, paragraph, view or page changes; atoms (fields,
-controls, images, note marks, breaks) are sliced whole, and one split across
-pages carries `partial` and an `anchor-only` diagnostic. Table
-fragments list their row window with `continuedFromPrevious`, `continuedOnNext`
-and `repeatedHeader`, and each cell paragraph has fragments of its own for the lines
-its cell shows (a line the cell cuts through is listed with a `clipped-content`
-diagnostic). Pages are
-laid out with revision markup, so while a laid-out story holds pending revisions a
-paged export reads the `markup` view, and `accepted` or `original` return
-`unsupported-revision-layout`. The other refusal codes are `stale-document`,
-`stale-layout` (stale section, settings or note metadata, fonts, options or
-`expectLayoutVersion`), `layout-unavailable`, `layout-not-converged` and
-`unsupported`.
-Geometry is off by default; rectangles are unzoomed CSS pixels (96 per inch) from
-the physical page's top-left corner. `maxFragments` (100,000 by default) and
-`maxLayoutBytes` bound the map separately and mark it `truncated`; mapping stops a
-page past the limit, so a truncated map leaves out the diagnostics of later pages
-and of paragraphs no page shows. With
-`pageMarkers`, Markdown follows each block marker with
-`<!-- docx-pages: 0=i 1=ii -->` (labels percent-encoded) and writes no page break
-into the text; a map from other content is refused. The map is `schemaVersion: 1`,
-versioned apart from the content: additive fields keep the version, and a change
-existing readers would misread bumps it.
-
-### Content controls
-
-List a document's content controls and fill its plain- and rich-text controls in
-one version-checked batch.
+`CollaborationProvider` from `@betteroffice/docx/collaboration` connects a replica to a binary
+transport. See the [collaboration guide](https://docs.betteroffice.dev/docs/collaboration)
+for shared state, transport wiring, checkpoints, and deployment.
 
-```ts
-const read = session.listContentControls();
-if (!read.ok) throw new Error(read.failure.message);
-const name = read.content.controls.find((control) => control.tag === 'customer.name')!;
-
-const result = session.applyEdits({
-  expectVersion: read.version,
-  steps: [
-    { op: 'setContentControlText', target: { kind: 'id', controlId: name.controlId }, text: 'Ada Lovelace' },
-    { op: 'setContentControlText', target: { kind: 'tag', tag: 'customer.address' }, text: '12 Example Street\nLondon' },
-  ],
-});
-```
+## Editor plugins
 
-Controls come in document order (body, headers, footers, footnotes, endnotes,
-comments; a control before the controls inside it), each with the structured
-export's control metadata (`controlId`, `ooxmlId`, `controlType`, `tag`, `alias`,
-`lock`, `showingPlaceholder`, `dataBound`) plus `placement`, `anchor`,
-`parentControlId`, `value` (its text with tabs as `\t` and line and paragraph
-breaks as LF, or `unavailable` with a reason), `multiLine` and `effectiveLock`,
-which folds in the locks of the controls containing it. `stories` narrows the read
-to some categories; `maxControls` (10,000) and `maxBytes` (8,388,608) refuse with
-`limit-exceeded` rather than returning part of the list, and `complete: false`
-includes coverage diagnostics. Tags, aliases and
-`ooxmlId`s match exactly and case-sensitively, and `findContentControls` returns
-every match. `listDocxContentControls(bytes)` and
-`findDocxContentControls(bytes, query)` read bytes without a session and throw
-`DocxContentControlsError` for refused options. Concurrent fills from
-collaborators resolve last-writer-wins for an inline control and merge like
-concurrent typing for a block control.
-
-A step's `target` is `{ kind: 'id', controlId }`, `{ kind: 'tag', tag }` or
-`{ kind: 'ooxmlId', ooxmlId }`. `controlId` is a locator scoped to the
-version or snapshot it was read at; list again after a version change. Tags are the template author's names for
-controls. `ooxmlId` is the control's authored `w:id`, the identity that survives
-save and reopen. A tag or `ooxmlId` write searches every story regardless of read
-filters and needs exactly one control in the document to carry it.
-
-`setContentControlText` replaces the content of a plain- or rich-text control
-with plain text and clears its placeholder flag everywhere it is recorded,
-leaving tags, aliases, ids, bindings and every other property as captured. CRLF
-becomes LF; LF is a line break, except in a rich-text block control, where it
-starts a paragraph: surviving paragraphs keep their ids and properties and new
-ones take the first paragraph's style defaults. A plain-text control accepts LF
-only when its `w:text` sets `w:multiLine` and keeps its lines in one paragraph.
-The text takes the formatting of the control's first text run, or the control's
-own run properties while it shows its placeholder. Equal text is a no-op unless
-the placeholder still shows or a plain-text control holds several paragraphs,
-which the fill joins into one. Refusals
-carry the batch code and a `reason`: `missing-control`, `missing-tag` or
-`missing-ooxml-id`, `ambiguous-control-id`, `ambiguous-tag` or
-`ambiguous-ooxml-id`, `content-locked`, `bound-control`,
-`unsupported-control-type`, `unsupported-children` (content other than text,
-tabs and line breaks, such as bookmarks, fields or tables), `nested-controls`,
-`unknown-lock`, `unsupported-suggestion`, `provenance-unavailable` (the session
-was not opened from DOCX bytes), `unsupported-story` (a control kept only in
-source XML, such as a comment body), `multiline-not-allowed` and `invalid-text`.
-Checkbox, dropdown and date controls keep `setContentControlValue`; a
-string passed to it fills a text control through the same step, and
-`clearContentControlValue` never erases a text control's text.
-
-### Compare documents into tracked changes
-
-Compare an original and a revised DOCX and get back the original with the
-body text differences as tracked insertions and deletions, attributed to the
-author and date you pass:
+For React host extensions, use the
+[DOCX plugin API](https://docs.betteroffice.dev/docs/javascript#host-docx-editor-plugins).
 
-```ts
-import { compareDocx } from '@betteroffice/docx';
-
-const result = await compareDocx(original, revised, {
-  author: 'Contract review',
-  date: '2024-05-06T09:30:00+02:00',
-  granularity: 'word',
-  unsupported: 'fail',
-});
-if (result.ok) {
-  for (const change of result.changes) console.log(change.id, change.kind, change.revised.text);
-} else {
-  console.warn(result.diagnostics.map((diagnostic) => diagnostic.code));
-}
-```
+Deprecated: `EditorPluginCore`, `PluginPanelProps`, `PanelConfig`, and `SidebarItemContext` from
+`@betteroffice/docx/plugin-api`; use `defineDocxPlugin` and `plugins` from `@betteroffice/docx-react`.
 
-`compareDocx` compares the text of body paragraphs whose structure is unchanged. Both
-packages are inspected in full before anything is authored, and any blocking
-difference refuses the comparison with `{ ok: false, diagnostics }`; no partial
-redline is ever returned. `unsupported: 'report'` keeps inspecting and returns
-every diagnostic, bounded by `limits.maxDiagnostics`. Blocking codes are
-`invalid-options`, `invalid-docx`, `existing-revisions` (anywhere, headers and
-property revisions included), `paragraph-insertion`, `paragraph-deletion`,
-`paragraph-move`, `ambiguous-alignment`, `table-change`, `structure-change`,
-`field-change`, `object-change`, `content-control-change`, `formatting-change`,
-`unsupported-content` and `unsupported-formatting` (a changed paragraph holding
-content, or run properties, that edits cannot carry, such as fields,
-hyperlinks, bookmarks, objects, page breaks, patterned shading or `w:lang`),
-`out-of-scope-change` (headers, footers, notes, comments), `opaque-part-change`,
-`provenance-unavailable`, `limit-exceeded`, `diagnostics-truncated`,
-`batch-refused`, `serialization-failed` and `roundtrip-mismatch`.
-`metadata-difference` (informational: modified dates, revision-session ids and
-document statistics, kept from the original) and `ambiguous-identity` (a
-warning: repeated paragraph ids, so changes are addressed by position) accompany
-a result. Every part whose content type or content is XML is scanned for
-revisions, and wrappers such as custom XML elements, body-level markers and
-every part must match exactly; an XML-typed part that cannot be read refuses the
-comparison.
-
-Paragraphs are aligned conservatively: text unique to one paragraph on each side
-anchors the alignment, crossing anchors are moves, one paragraph against one
-between anchors is a replacement, and several need shared words and exactly one
-best correspondence. Clearing a paragraph's text is a deletion; the paragraph
-mark stays. Differences are reported by Unicode word, keeping punctuation and
-whitespace tokens, or with `granularity: 'char'` by grapheme cluster. Each
-change is one tracked replacement: deleted text keeps its formatting and
-inserted text takes the revised formatting. Changes are ordered by original
-position, `id` is `change-0`, `change-1` and so on, and their spans address the
-inputs by part, SHA-256 and element-child path with paragraph-local UTF-16
-offsets. `date` must be RFC 3339 with an explicit offset and is recorded in UTC;
-the clock is never read. `author` must not be blank.
-
-Only the changed paragraphs' content is rewritten; their start tags and
-properties, every other paragraph and every other part keep the original's
-bytes, and identical inputs return the original bytes. Rewritten runs carry the
-session's formatting vocabulary, so run properties a style supplies are written
-as direct formatting, and complex-script fonts, sizes, bold and italic are
-written only as the source states them. The result is reopened and checked
-against both inputs before it is returned, with each run's effective formatting
-read from the XML, style toggles such as bold combined across every level of a
-style's `basedOn` chain; a difference refuses with `roundtrip-mismatch`.
-Defaults, which are also the ceilings: 32 MiB per input, 128 MiB inflated,
-10,000 paragraphs per input and 1,048,576 UTF-16 units of text in both inputs,
-counted across every story while the parts are read, 250,000 alignment cells,
-4,000,000 diff cells, 128 changes, 256 diagnostics, 64 MiB of staged state,
-8 MiB of result JSON without the output package (at least 1 KiB) and a 64 MiB
-output, the no-op included.
-Review in BetterOffice is tested.
-
-### Editor plugin contract (deprecated)
-
-`@betteroffice/docx/plugin-api` keeps its geometry and sidebar building blocks:
-`RenderedDomContext`, `PositionCoordinates`, `SidebarItem`,
-`createRenderedDomContext`, `createCanvasHostProjector` and
-`resolveItemPositions`. The snapshot-based `EditorPluginCore`,
-`PluginPanelProps`, `PanelConfig` and `SidebarItemContext` are deprecated: they
-pass serialized `Document` snapshots and have no host that manages their
-lifecycle. Host plugins for the React editor use `defineDocxPlugin` and the
-`plugins` prop of
-[`@betteroffice/docx-react`](https://www.npmjs.com/package/@betteroffice/docx-react),
-which provide versioned reads, granted commands and edit batches, lifecycle
-events and cleanup.
-
-### Reanchor an existing comment
-
-`session.setCommentRanges(commentId, ranges)` replaces only the sticky anchors of
-an existing comment. The id, author, date, body, reply relationship and resolution
-state remain intact. Ranges use the same paragraph locations as `addComment`;
-one range may span paragraphs, and separate ranges may address different stories.
-
-Every range must be non-empty, ordered, and within existing paragraphs. An empty
-list, unknown comment/story/paragraph, or invalid offset throws before any content
-changes. The host supplies the surviving text's new range.
-
-If replacement removes all commented text, the host must explicitly choose a new
-non-empty range or handle the comment's removal. Rejected reanchoring leaves the
-comment unchanged and does not roll back a text replacement already performed.
-
-`saveYrsDocx()` writes the current ranges under the comment's own ID, with its
-author, date, body, replies and resolution.
-
-Reanchoring joins the current local undo capture, so an immediate replacement and
-reanchor can undo together. Comment edits participate in the session's history;
-undoing comment changes conservatively invalidates all stories for saved anchors.
-
-The undo manager retains comment item boundaries with their undo/redo entries so
-anchors inside replaced text survive repeated history traversal with Yrs 0.27.
-Discarding history releases its bookkeeping; undo/redo traverses a local snapshot
-when those boundaries need restoration.
-
-### External drop positions
-
-`RenderedDomContext.getPositionAtPoint(clientX, clientY)` queries the same canvas
-hit testing used for the caret. Pass viewport coordinates, such as a drop event's
-`clientX` and `clientY`. Page scroll and CSS zoom are resolved from the live page
-geometry. The query never changes selection or focus.
-
-The result contains `position`, `pageIndex`, and `region`. Header/footer hits also
-carry `rId`; footnote/endnote hits carry `noteId`. Positions are local to that
-region's display stream in the layout the context renders, and shift with every
-edit.
-
-In React, `editorRef.getPositionAtPoint(clientX, clientY)` runs the same query and
-adds `version` and `target`: the collapsed accepted-view range at the point, keyed
-by session paragraph keys, in the body, header, footer, note or table cell story
-the point is in. Use it as a text step's target with `expectVersion: version`:
+## Fonts for custom adapters
 
-```ts
-const hit = editorRef.current!.getPositionAtPoint(event.clientX, event.clientY);
-if (hit) {
-  await editorRef.current!.applyEdits({
-    expectVersion: hit.version,
-    steps: [{ op: 'insertText', target: hit.target, at: 'start', text: '{{customer.name}}' }],
-  });
-}
-```
+See [font setup](https://docs.betteroffice.dev/docs/packages#fonts) for optional measurement assets.
+For browser font loading, `createFontLoadScope()` from `@betteroffice/docx/utils` isolates each
+editor's load notifications. `registerDocumentFaces(faces, scope)` registers embedded faces and
+returns their CSS family aliases when documents use different bytes under the same family name.
+Release the scope with `scope.dispose()` when its editor is removed.
+
+## Documentation
 
-It returns `null` while typed or composed input is pending and until the painted
-pages show the current version (retry after `flushPendingInput()` or on the next
-frame), and a batch applied after further typing refuses with `stale-version`, so a
-drop never lands at a shifted position. Plugins get the same query as
-`context.geometry.getPositionAtPoint`, with the layout's `layoutId`. The lower-level
-`editorRef.getEditorRef()?.displayPositionToYrsLoc(hit)` maps a hit to its live
-`YrsLoc` (offsets that count text a pending deletion hides) without the version
-check; passing a number to it retains body mapping.
-
-Text runs and their editable content boxes are accepted. Page margins, images,
-page gaps, points outside pages, and queries without ready canvas geometry return
-`null`.
-
-### Font loads per editor
-
-Several editors can share one page. `createFontLoadScope()` gives each its own
-font loads: `onFontsLoaded` and `onFontError` on a scope hear the loads made
-through it and module-level ones, never another scope's. `registerDocumentFaces(faces, scope)`
-registers a document's embedded faces under their own family names, or under
-an alias when another open document embeds different faces under the same name,
-and resolves to the family each was registered under. Draw with that map as
-`DrawPageOptions.fontFamilies`. The scope holds the faces until its next
-document or `dispose()`. `loadEmbeddedFontFamilies` does the same from a
-package's font table.
+- [JavaScript guide](https://docs.betteroffice.dev/docs/javascript)
+- [Collaboration guide](https://docs.betteroffice.dev/docs/collaboration)
+- [Package guide](https://docs.betteroffice.dev/docs/packages)
+- [React editor on npm](https://www.npmjs.com/package/@betteroffice/docx-react)
+- [Locale strings on npm](https://www.npmjs.com/package/@betteroffice/docx-i18n)
+- [Repository](https://github.com/openooxml/betteroffice)