@beyondwork/docx-react-component 1.0.21 → 1.0.23

package/README.md

@@ -1,14 +1,33 @@
+---
+title: React OOXML Office
+summary: Shipped docx package landing page and primary router into consumer, wrapper, agent, and maintainer documentation.
+audience: consumer, wrapper, agent, maintainer
+stability: main-path
+docRole: main-path
+canonical: true
+---
+
 # React OOXML Office
 
 [![CI](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml)
 
-`@beyondwork/docx-react-component` is the shipped product in this repository: `WordReviewEditor`, a fidelity-first React editor for legal-review-safe `docx` workflows. Waves 20 through 23 land live table editing, package distribution, validator-backed CI, and legal workflow helpers. Wave 24 is the next production-hardening packet.
+`@beyondwork/docx-react-component` is the shipped product in this repository: a fidelity-first React docx editor centered on `WordReviewEditor`.
+
+## Use This README For
+
+- confirming what is shipped today
+- installing the package
+- finding the right documentation lane quickly
+
+Do not use this README as the full package contract. The canonical consumer path starts in `docs/README.md`, `docs/reference/public-api.md`, and `docs/reference/integration-guide.md`.
 
-The broader repository is still evolving toward a layered `react-ooxml-office` platform, but the source reality is unchanged:
+## Current Package Reality
+
+The repository may also carry broader branch-local work, but the shipped contract today is still docx-first:
 
 - `docx` is the only implemented and shipped runtime contract
-- `xlsx` is the next planned OOXML sibling
-- `pdf` is future work and outside the first shared OOXML platform contract
+- `xlsx` is planned work, not part of the current package contract
+- `pdf` remains future work outside the current package boundary
 
 ## Install
 
@@ -54,12 +73,27 @@ Snapshot/export note:
 - when a session starts from a real `.docx`, persisted snapshots now carry embedded source-package provenance so later snapshot-origin `.docx` export can use the same package-backed exporter
 - legacy snapshots without that provenance still load, but `.docx` export is intentionally blocked rather than falling back to a lossy minimal package
 
-The current public ESM exports are:
-
-- `@beyondwork/docx-react-component` -> `WordReviewEditor`
-- `@beyondwork/docx-react-component/public-types` -> public TypeScript contracts
-- `@beyondwork/docx-react-component/ui-tailwind` -> current Tailwind UI primitives
-- `@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css` -> shipped theme variables and Tailwind theme import
+The current shipped ESM exports include:
+
+- stable default entrypoints:
+  - `@beyondwork/docx-react-component`
+  - `@beyondwork/docx-react-component/public-types`
+  - `@beyondwork/docx-react-component/ui-tailwind`
+  - `@beyondwork/docx-react-component/legal`
+  - `@beyondwork/docx-react-component/compare`
+  - `@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css`
+- advanced-supported subpaths for wrapper teams and package-adjacent integrations:
+  - `@beyondwork/docx-react-component/runtime/document-runtime`
+  - `@beyondwork/docx-react-component/io/docx-session`
+  - `@beyondwork/docx-react-component/core/commands/*`
+  - `@beyondwork/docx-react-component/core/selection/mapping`
+  - `@beyondwork/docx-react-component/core/state/editor-state`
+  - `@beyondwork/docx-react-component/ui-tailwind/editor-surface/search-plugin`
+- alias subpaths:
+  - `@beyondwork/docx-react-component/tailwind`
+  - `@beyondwork/docx-react-component/api/public-types`
+
+Use `docs/reference/public-api.md` and `docs/reference/public-api.manifest.json` for the current contract inventory and stability guidance.
 
 ## Product Contract
 
@@ -74,48 +108,56 @@ For the current shipped `docx` implementation, that specifically means:
 - preserve unsupported but preservable OOXML
 - remain editable in Word after export
 
-## Repository Direction
+For the normative API and host contract, use:
 
-This repo is broadening from the original docx-first editor into a layered shared-OOXML story:
+- [`docs/reference/public-api.md`](docs/reference/public-api.md)
+- [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
+- [`docs/reference/ooxml-compliance.md`](docs/reference/ooxml-compliance.md)
 
-- shared platform concerns for package IO, preservation, diagnostics, and validation
-- format-specific runtimes with explicit capability boundaries
-- host-facing review and editing surfaces for each supported format
+## Documentation Map
 
-The canonical shared-platform overview lives in `docs/architecture/platform/shared-openxml-editor-platform.md`.
+### Start Here
 
-## Documentation Map
+- [`docs/README.md`](docs/README.md)
 
-Start here:
+### Main Consumer Path
 
-- `AGENTS.md`
-- `DESIGN.md`
-- `docs/README.md`
-- `docs/roadmap.md`
-- `docs/plans/current-state.md`
-- `docs/plans/master-plan.md`
+- [`docs/reference/quick-start.md`](docs/reference/quick-start.md)
+- [`docs/reference/consumer-matrix.md`](docs/reference/consumer-matrix.md)
+- [`docs/reference/public-api.md`](docs/reference/public-api.md)
+- [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
 
-Current shipped docx contracts:
+### Wrapper And Agent Path
 
-- `docs/reference/public-api.md`
-  This doc separates the shipped Waves 20-23 surface from the future Waves 25 through 27 ref expansion.
-- `docs/reference/ooxml-compliance.md`
-- `docs/reference/word-review-editor-frontend-architecture.md`
-- `docs/reference/word-review-editor-ux-guide.md`
+- [`docs/reference/consumer-matrix.md`](docs/reference/consumer-matrix.md)
+- [`docs/reference/agent-integration-guide.md`](docs/reference/agent-integration-guide.md)
+- [`docs/reference/public-api.md`](docs/reference/public-api.md)
+- [`docs/reference/service-wrapper-guidance.md`](docs/reference/service-wrapper-guidance.md)
+- [`docs/reference/agent-capability-map.md`](docs/reference/agent-capability-map.md)
+- [`docs/reference/agent-read-models-and-snapshots.md`](docs/reference/agent-read-models-and-snapshots.md)
+- [`docs/reference/agent-workflow-and-suggestions.md`](docs/reference/agent-workflow-and-suggestions.md)
+- [`docs/reference/scope-aware-selection-tooling.md`](docs/reference/scope-aware-selection-tooling.md)
+- [`docs/reference/editor-integration-style.md`](docs/reference/editor-integration-style.md)
+- [`docs/reference/beyondwork-runtime-environment.md`](docs/reference/beyondwork-runtime-environment.md)
 
-Shared platform and planned xlsx docs:
+Wrapper and agent docs stay on `main`, but they are downstream integration guidance rather than the canonical package contract.
 
-- `docs/architecture/platform/shared-openxml-editor-platform.md`
-- `docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md`
-- `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
-- `docs/reference/xlsx/xlsx-ooxml-compliance.md`
-- `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
-- `docs/xlsx-react/README.md`
+Current integration honesty:
+
+- the shipped React host surface is still `WordReviewEditor`
+- `showReviewPanel={false}` only hides the bundled review rail
+- a distinct public chromeless React surface is not yet shipped
+
+### Maintainer Path
+
+- [`docs/maintainers/README.md`](docs/maintainers/README.md)
+
+Maintainer prompts, operator runbooks, and proof/closure material remain important, but they are not the first reading path for package consumers.
 
 ## Packaging And Release
 
 - `.github/workflows/publish.yml` publishes on `v*` tags after verifying the tag matches `package.json`
-- `pnpm pack --dry-run` is the baseline package proof for this wave
+- `pnpm pack --dry-run` is the baseline package proof
 - npm provenance is enabled in `publishConfig` and in the publish workflow invocation
 - the published package currently ships source ESM entry points plus TypeScript source-backed `types` exports
 - the Microsoft Open XML SDK remains CI/internal-service only, never part of the shipped browser runtime
@@ -129,9 +171,692 @@ Shared platform and planned xlsx docs:
 - keep docs honest about shipped versus planned behavior
 - add or extend fixtures for compatibility-critical changes
 - `bash scripts/validate-fixtures.sh` now uses the Railway validator service and requires `OPENXML_VALIDATOR_AUTH_TOKEN` when hitting the public domain
+- `node scripts/validate-docs-navigation.mjs` enforces the core docs catalog, required indexes, and frontmatter contract
 
 ## Guiding Principle
 
 This repo is not trying to become a generic office clone.
 
 It is building fidelity-first office-document runtimes with explicit preservation and calm, reviewable UI.
+
+## Using the package
+
+### WordReviewEditor
+
+`WordReviewEditor` is a React component for loading, editing, and exporting `.docx` files with full comment and tracked-change (redline) support. It is exported from `@beyondwork/docx-react-component`.
+
+### Installation
+
+```tsx
+import {
+  WordReviewEditor,
+  type WordReviewEditorRef,
+  type WordReviewEditorProps,
+  type WordReviewEditorEvent,
+} from "@beyondwork/docx-react-component";
+```
+
+### Basic mount
+
+```tsx
+import { useRef } from "react";
+import { WordReviewEditor, type WordReviewEditorRef } from "@beyondwork/docx-react-component";
+
+export function MyEditor({ docxBytes }: { docxBytes: Uint8Array }) {
+  const editorRef = useRef<WordReviewEditorRef>(null);
+
+  return (
+    <WordReviewEditor
+      ref={editorRef}
+      documentId="doc-001"
+      currentUser={{ userId: "u1", displayName: "Alice" }}
+      initialDocx={docxBytes}
+      onEvent={(event) => console.log(event)}
+    />
+  );
+}
+```
+
+---
+
+### Props reference
+
+| Prop | Type | Description |
+|---|---|---|
+| `documentId` | `string` | **Required.** Stable identifier for this document. |
+| `currentUser` | `EditorUser` | **Required.** The user performing edits and adding comments. |
+| `initialDocx` | `Uint8Array \| ArrayBuffer` | Raw `.docx` bytes to load on first mount. |
+| `initialSessionState` | `EditorSessionState` | Previously saved session state to restore. |
+| `initialSnapshot` | `PersistedEditorSnapshot` | Previously saved snapshot to restore. |
+| `externalDocSource` | `ExternalDocumentSource` | Alternative source with explicit `kind` (`"docx"`, `"session"`, `"snapshot"`). |
+| `readOnly` | `boolean` | When `true`, all editing commands are disabled. |
+| `reviewMode` | `"editing" \| "review"` | Shell layout hint — affects toolbar/panel arrangement but not editing authority. |
+| `markupDisplay` | `"clean" \| "simple" \| "all"` | Controls tracked-change visibility. |
+| `showReviewPanel` | `boolean` | Shows or hides the right-side comment and tracked-change panel. |
+| `autosave` | `AutosaveConfig` | Enables automatic saving. |
+| `hostAdapter` | `EditorHostAdapter` | Callbacks for `load`, `saveSession`, `saveExport`. |
+| `datastore` | `EditorDatastoreAdapter` | Alternative persistence adapter with `load`, `saveSnapshot`. |
+| `onEvent` | `(event: WordReviewEditorEvent) => void` | Unified event handler (see [Events](#events)). |
+| `onWarning` | `(warning: EditorWarning) => void` | Fired for non-fatal warnings. |
+| `onError` | `(error: EditorError) => void` | Fired for fatal errors. |
+
+#### EditorUser
+
+```ts
+interface EditorUser {
+  userId: string;
+  displayName: string;
+  email?: string;
+  avatarUrl?: string;
+}
+```
+
+#### AutosaveConfig
+
+```ts
+interface AutosaveConfig {
+  enabled?: boolean;
+  debounceMs?: number; // default: 2000
+}
+```
+
+---
+
+### Show / hide UI regions
+
+#### Review panel
+
+The right-side panel lists comment threads and tracked changes.
+
+```tsx
+<WordReviewEditor showReviewPanel={false} ... />  // hide panel
+<WordReviewEditor showReviewPanel={true}  ... />  // show panel (default)
+```
+
+#### Tracked-change display mode
+
+`markupDisplay` controls how tracked changes appear in the document body.
+
+| Value | Behaviour |
+|---|---|
+| `"clean"` | Show the accepted version — insertions visible, deletions hidden. |
+| `"simple"` | Show a simplified view of changes without inline markup. |
+| `"all"` | Show all insertion and deletion marks inline (Word's "Show Markup" mode). |
+
+```tsx
+<WordReviewEditor markupDisplay="clean" ... />
+```
+
+You can also change the display mode at runtime:
+
+```ts
+// no ref method for markupDisplay — pass as a prop; React re-renders propagate the change.
+```
+
+#### Document mode
+
+`DocumentMode` controls editing authority, not just appearance.
+
+| Mode | Effect |
+|---|---|
+| `"editing"` | Edits are applied directly (no tracking). |
+| `"suggesting"` | Every edit is automatically wrapped in a tracked change. |
+| `"viewing"` | Document is read-only regardless of the `readOnly` prop. |
+
+Set via ref:
+
+```ts
+editorRef.current.setDocumentMode("suggesting");
+```
+
+Or pass `reviewMode="review"` as a prop to start in a review-friendly shell layout (the component internally maps this to `"suggesting"` document mode).
+
+#### Read-only mode
+
+```tsx
+<WordReviewEditor readOnly={true} ... />
+```
+
+All editing, commenting, and tracked-change commands are blocked. The toolbar is still rendered but all buttons are disabled.
+
+#### Workspace layout
+
+```ts
+editorRef.current.setWorkspaceMode("canvas"); // continuous scroll
+editorRef.current.setWorkspaceMode("page");   // paginated view
+```
+
+---
+
+### Imperative ref
+
+Obtain the ref via `useRef<WordReviewEditorRef>()`:
+
+```tsx
+const editorRef = useRef<WordReviewEditorRef>(null);
+<WordReviewEditor ref={editorRef} ... />
+
+// then:
+editorRef.current?.addComment({ body: "Needs revision" });
+```
+
+---
+
+### Comment operations
+
+#### Add a comment
+
+```ts
+addComment(params: AddCommentParams): string
+// returns the new commentId
+```
+
+```ts
+interface AddCommentParams {
+  anchor?: EditorAnchorProjection; // defaults to the current selection
+  body?: string;
+  authorId?: string;               // defaults to currentUser.userId
+}
+```
+
+**Important**: if you want the comment to land on a specific text selection, capture the anchor *before* opening any draft UI (e.g. a modal or popover), because opening a modal typically collapses the editor selection.
+
+```ts
+// 1. Capture anchor while text is still selected
+const snapshot = editorRef.current.getRenderSnapshot();
+const anchor = snapshot.selection.activeRange;
+
+// 2. Open your draft UI, let user type a message...
+// 3. On submit:
+const commentId = editorRef.current.addComment({ anchor, body: draftText });
+```
+
+#### Resolve a comment
+
+```ts
+editorRef.current.resolveComment(commentId);
+```
+
+Marks the thread as resolved. The comment remains in the document and can be exported; it is moved to the resolved list in the sidebar.
+
+#### Reopen a resolved comment
+
+```ts
+editorRef.current.reopenComment(commentId);
+```
+
+#### Delete a comment permanently
+
+```ts
+editorRef.current.deleteComment(commentId);
+```
+
+Removes the comment entirely. Use this to clean up failed or unwanted drafts.
+
+#### Add a reply to an existing thread
+
+```ts
+editorRef.current.addCommentReply(commentId, "Reply text here");
+```
+
+#### Edit a comment body
+
+```ts
+editorRef.current.editCommentBody(commentId, "Updated text");
+```
+
+#### Scroll to a comment
+
+```ts
+editorRef.current.scrollToComment(commentId);
+```
+
+#### Open (focus) a comment in the sidebar
+
+```ts
+editorRef.current.openComment(commentId);
+```
+
+#### Get all comments
+
+```ts
+const sidebar: CommentSidebarSnapshot = editorRef.current.getComments();
+```
+
+```ts
+interface CommentSidebarSnapshot {
+  activeCommentId?: string;
+  openCommentIds: string[];
+  resolvedCommentIds: string[];
+  detachedCommentIds: string[];
+  totalCount: number;
+  threads: CommentSidebarThreadSnapshot[];
+}
+
+interface CommentSidebarThreadSnapshot {
+  commentId: string;
+  status: "open" | "resolved" | "detached";
+  anchor: EditorAnchorProjection;
+  excerpt: string;               // the anchored text snippet
+  entries: CommentSidebarThreadEntrySnapshot[];
+  entryCount: number;
+  createdAt: string;             // ISO 8601
+  createdBy: string;             // userId
+  resolvedAt?: string;
+  resolvedBy?: string;
+}
+```
+
+#### Detached comments
+
+A comment becomes **detached** when the text it was anchored to is deleted. Detached comments:
+
+- Still appear in `sidebar.detachedCommentIds` and have `status: "detached"`.
+- Have `anchor.kind === "detached"` with a `lastKnownRange` and a `reason` (`"deleted"`, `"invalidatedByStructureChange"`, or `"importAmbiguity"`).
+- Do **not** block DOCX export.
+- Can be resolved, reopened, or deleted via the same methods above.
+
+---
+
+### Tracked-change operations
+
+#### Get all tracked changes
+
+```ts
+const changes: TrackedChangesSnapshot = editorRef.current.getTrackedChanges();
+```
+
+```ts
+interface TrackedChangesSnapshot {
+  pendingChangeIds: string[];
+  acceptedChangeIds: string[];
+  rejectedChangeIds: string[];
+  detachedChangeIds: string[];
+  actionableChangeIds: string[];
+  preserveOnlyChangeIds: string[];
+  totalCount: number;
+  revisions: TrackedChangeEntrySnapshot[];
+}
+
+interface TrackedChangeEntrySnapshot {
+  revisionId: string;
+  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
+  status: "active" | "accepted" | "rejected" | "detached";
+  actionability: "actionable" | "preserve-only";
+  canAccept: boolean;
+  canReject: boolean;
+  anchor: EditorAnchorProjection;
+  anchorLabel: string;
+  excerpt?: string;
+  detail?: string;
+  authorId: string;
+  createdAt: string;
+}
+```
+
+`preserve-only` revisions (`formatting`, `move`) can be displayed but cannot be individually accepted or rejected through the API.
+
+#### Accept a single change
+
+```ts
+editorRef.current.acceptChange(revisionId);
+```
+
+#### Reject a single change
+
+```ts
+editorRef.current.rejectChange(revisionId);
+```
+
+#### Accept all pending changes
+
+```ts
+editorRef.current.acceptAllChanges();
+```
+
+#### Reject all pending changes
+
+```ts
+editorRef.current.rejectAllChanges();
+```
+
+#### Scroll to a tracked change
+
+```ts
+editorRef.current.scrollToRevision(revisionId);
+```
+
+---
+
+### Export
+
+```ts
+const result = await editorRef.current.exportDocx({ fileName: "output.docx" });
+// result.bytes is the Uint8Array of the .docx file
+```
+
+Export will throw if any non-detached comment no longer maps to a serializable range in the document. To diagnose, check `getComments().threads` for entries where `status !== "detached"` but whose `anchor.kind` is unexpected.
+
+---
+
+### Events
+
+All events are dispatched through the single `onEvent` prop. The `type` discriminator narrows the payload.
+
+```tsx
+<WordReviewEditor
+  onEvent={(event) => {
+    if (event.type === "comment_added") {
+      console.log("New comment:", event.commentId);
+    }
+  }}
+/>
+```
+
+#### `ready`
+
+Fired once after the document finishes loading and the editor is interactive.
+
+```ts
+{
+  type: "ready";
+  documentId: string;
+  sessionId: string;
+  source: "docx" | "session" | "snapshot";
+  stats: DocumentStats;          // storyLength, commentCount, revisionCount
+  compatibility: CompatibilityReport;
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+}
+```
+
+#### `comment_added`
+
+Fired when a new comment thread is created (via `addComment` or the toolbar).
+
+```ts
+{
+  type: "comment_added";
+  documentId: string;
+  commentId: string;
+  anchor: EditorAnchorProjection;
+}
+```
+
+#### `comment_resolved`
+
+Fired when a comment is resolved (via `resolveComment` or the sidebar).
+
+```ts
+{
+  type: "comment_resolved";
+  documentId: string;
+  commentId: string;
+}
+```
+
+There is no separate `comment_removed` event — deletions are silent. Query `getComments()` after a `dirty_changed` event if you need to detect deletions.
+
+#### `change_accepted`
+
+Fired when a tracked change is accepted.
+
+```ts
+{
+  type: "change_accepted";
+  documentId: string;
+  changeId: string;
+}
+```
+
+#### `change_rejected`
+
+Fired when a tracked change is rejected.
+
+```ts
+{
+  type: "change_rejected";
+  documentId: string;
+  changeId: string;
+}
+```
+
+#### `selection_changed`
+
+Fired whenever the editor cursor or selection changes.
+
+```ts
+{
+  type: "selection_changed";
+  documentId: string;
+  selection: SelectionSnapshot;
+}
+
+interface SelectionSnapshot {
+  anchor: number;
+  head: number;
+  isCollapsed: boolean;
+  activeRange: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+}
+```
+
+Use `selection.activeRange` as the `anchor` argument to `addComment` — but capture it *before* opening any modal UI.
+
+#### `dirty_changed`
+
+Fired when the document transitions between clean and dirty (unsaved) states.
+
+```ts
+{
+  type: "dirty_changed";
+  documentId: string;
+  isDirty: boolean;
+}
+```
+
+#### `story_changed`
+
+Fired when the user navigates between document stories (e.g. main body → header/footer).
+
+```ts
+{
+  type: "story_changed";
+  documentId: string;
+  activeStory: EditorStoryTarget;
+}
+```
+
+#### `export_completed`
+
+Fired after a successful `exportDocx` call, after the host `saveExport` callback (if any) has resolved.
+
+```ts
+{
+  type: "export_completed";
+  documentId: string;
+  result: ExportResult;   // result.bytes, result.fileName, result.mimeType
+}
+```
+
+#### `session_saved`
+
+Fired after the host `saveSession` callback resolves.
+
+```ts
+{
+  type: "session_saved";
+  documentId: string;
+  sessionState: EditorSessionState;
+  savedAt: string;
+  isAutosave: boolean;
+}
+```
+
+#### `snapshot_saved`
+
+Fired after the datastore `saveSnapshot` callback resolves.
+
+```ts
+{
+  type: "snapshot_saved";
+  documentId: string;
+  snapshot: PersistedEditorSnapshot;
+  isAutosave: boolean;
+}
+```
+
+#### `autosave_state`
+
+Fired when the autosave lifecycle transitions.
+
+```ts
+{
+  type: "autosave_state";
+  documentId: string;
+  state: "idle" | "pending" | "saving" | "saved" | "error";
+}
+```
+
+#### `warning_added` / `warning_cleared`
+
+Non-fatal import or rendering warnings.
+
+```ts
+{ type: "warning_added";   documentId: string; warning: EditorWarning; }
+{ type: "warning_cleared"; documentId: string; warningId: string; code: EditorWarningCode; }
+```
+
+#### `error`
+
+Fatal editor error. The editor may be in an unrecoverable state after this event.
+
+```ts
+{
+  type: "error";
+  documentId: string;
+  error: EditorError;    // error.code, error.message, error.isFatal
+}
+```
+
+#### Workflow events
+
+These events relate to the optional workflow overlay feature.
+
+```ts
+{ type: "workflow_overlay_changed";          documentId: string; snapshot: WorkflowScopeSnapshot; }
+{ type: "workflow_active_work_item_changed"; documentId: string; activeWorkItemId: string | null; }
+{ type: "command_blocked";                   documentId: string; command: string; reasons: WorkflowBlockedCommandReason[]; }
+```
+
+---
+
+### Key types
+
+#### EditorAnchorProjection
+
+Describes a position or range in the document. Returned by `selection.activeRange` and stored on comments/revisions.
+
+```ts
+type EditorAnchorProjection =
+  | { kind: "range";    from: number; to: number; assoc: { start: -1|1; end: -1|1 } }
+  | { kind: "node";     at: number;  assoc: -1|1 }
+  | { kind: "detached"; lastKnownRange: { from: number; to: number };
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity" };
+```
+
+A `"range"` anchor is required for `addComment` if the document contains tables or the selection spans multiple characters. The `from`/`to` positions are in the editor's internal runtime coordinate space — always capture them from `getRenderSnapshot().selection.activeRange`, never construct them manually.
+
+#### DocumentMode
+
+```ts
+type DocumentMode = "editing" | "suggesting" | "viewing";
+```
+
+#### WorkspaceMode
+
+```ts
+type WorkspaceMode = "canvas" | "page";
+```
+
+---
+
+### Common patterns
+
+#### Full add-comment flow with custom UI
+
+```tsx
+function CommentButton({ editorRef }: { editorRef: React.RefObject<WordReviewEditorRef> }) {
+  const [draft, setDraft] = useState<{ anchor: EditorAnchorProjection; text: string } | null>(null);
+
+  function openDraft() {
+    // Capture anchor BEFORE the modal steals focus from the editor
+    const snapshot = editorRef.current?.getRenderSnapshot();
+    if (!snapshot) return;
+    const anchor = snapshot.selection.activeRange;
+    if (anchor.kind !== "range" || anchor.from === anchor.to) return;
+    setDraft({ anchor, text: "" });
+  }
+
+  function submit() {
+    if (!draft) return;
+    editorRef.current?.addComment({ anchor: draft.anchor, body: draft.text });
+    setDraft(null);
+  }
+
+  return (
+    <>
+      <button onClick={openDraft}>Comment</button>
+      {draft && (
+        <dialog open>
+          <textarea value={draft.text} onChange={(e) => setDraft({ ...draft, text: e.target.value })} />
+          <button onClick={submit}>Add</button>
+          <button onClick={() => setDraft(null)}>Cancel</button>
+        </dialog>
+      )}
+    </>
+  );
+}
+```
+
+#### Listen for comment and review-change events
+
+```tsx
+<WordReviewEditor
+  onEvent={(event) => {
+    switch (event.type) {
+      case "comment_added":
+        console.log("comment added:", event.commentId, event.anchor);
+        break;
+      case "comment_resolved":
+        console.log("comment resolved:", event.commentId);
+        break;
+      case "change_accepted":
+        console.log("change accepted:", event.changeId);
+        break;
+      case "change_rejected":
+        console.log("change rejected:", event.changeId);
+        break;
+    }
+  }}
+/>
+```
+
+#### Resolve all open comments programmatically
+
+```ts
+const { threads } = editorRef.current.getComments();
+for (const thread of threads) {
+  if (thread.status === "open") {
+    editorRef.current.resolveComment(thread.commentId);
+  }
+}
+```
+
+#### Accept or reject all actionable changes
+
+```ts
+editorRef.current.acceptAllChanges();
+// or
+editorRef.current.rejectAllChanges();
+```