@betteroffice/docx 0.2.1 → 0.4.0

package/README.md

@@ -53,9 +53,9 @@ provider.connect();
 
 `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 speaks Yjs sync-v1;
-room routing, authentication, awareness, and reconnection policy remain
-transport concerns. Pass a persisted Yrs update as `collaboration.initialUpdate`
+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.
 
@@ -68,3 +68,586 @@ Package builds, demo startup, and CI run this step automatically.
 
 [JavaScript guide](https://docs.betteroffice.dev/docs/javascript) ·
 [Changelog](https://github.com/openooxml/betteroffice/blob/main/packages/docx/CHANGELOG.md) · Apache-2.0.
+
+### Undo capture modes and boundaries
+
+`session.setUndoCaptureMode(mode)` selects how tracked local transactions are
+combined into undo steps. `session.undoCaptureMode()` returns the current mode.
+
+| 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. |
+
+`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.
+
+```ts
+session.setUndoCaptureMode('manual');
+session.insertText(firstLocation, 'Prefixo ');
+session.insertText(secondLocation, 'Suffix');
+session.addUndoBoundary();
+session.deleteRange(markerRange);
+session.addUndoBoundary();
+session.setUndoCaptureMode('auto');
+```
+
+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.
+
+### Paragraph identities
+
+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.
+
+`saveYrsDocx(session)` saves a session opened from DOCX bytes and returns each saved
+paragraph's persisted anchor, qualified by its package part:
+
+```ts
+import { createYrsSession, saveYrsDocx } from '@betteroffice/docx/yrs';
+
+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;
+
+const reopened = await createYrsSession();
+reopened.openDocx(saved.bytes, true);
+reopened.resolveParagraphAnchor(anchor); // { status: 'found', anchor: { kind: 'session', … } }
+```
+
+`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.
+
+```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);
+```
+
+`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.
+
+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.
+
+| 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:
+
+```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',
+    },
+  ],
+});
+```
+
+`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.
+
+```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' });
+```
+
+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.
+
+```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 });
+```
+
+`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.
+
+```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' },
+  ],
+});
+```
+
+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:
+
+```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));
+}
+```
+
+`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`:
+
+```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}}' }],
+  });
+}
+```
+
+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.