@beyondwork/docx-react-component 1.0.70 → 1.0.72

package/README.md

@@ -11,136 +11,1025 @@ canonical: true
 
 [![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)
 
-Embeddable backoffice components for the [Beyond Work](https://beyondwork.ai) runtime. This repository ships **`@beyondwork/docx-react-component`** — a fidelity-first React `.docx` editor for legal review, contract negotiation, and any workflow where documents round-trip through Microsoft Word without damage.
+This repository builds **backoffice work components** for the [Beyond Work](https://beyondwork.ai) runtime — embeddable, composable modules that handle document editing, review workflows, data processing, and task automation inside enterprise workspaces.
 
-**Design principle — human-AI parity.** Every capability in the UI has an equivalent, structured API. The agent and the user operate on the same runtime, the same commands, the same read models. There is no "agent-only" shortcut and no "human-only" feature.
+The design principle across every component: **advanced tasks should be equally easy for AI agents and human users.** Every capability exposed through the UI is also available through a structured API. Every API is designed so an agent can inspect state, reason about it, and act on it without special accommodation. Humans and agents share the same runtime, the same commands, the same read models, and the same fidelity guarantees.
 
----
+## Use This README For
+
+- confirming what is shipped today vs coming
+- 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`](docs/reference/public-api.md) (V1 + V2), [`docs/reference/public-api-3.md`](docs/reference/public-api-3.md) (V3 additive surface), and [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md).
+
+The target end-state architecture — 11-layer stack, Runtime/AI/UI API split, semantic scope compiler, and Phase 0–7 migration plan — is documented in [`docs/architecture/00-overview.md`](docs/architecture/00-overview.md). Read it before designing cross-cutting changes. The technical wiki under [`docs/wiki/`](docs/wiki/) has feature-level pages (API v1/v2/v3, runtime-truth, debugging, doc-debug-service-guide, chrome-composition / chrome-composition-backlog, testing-and-fixtures, etc.); navigate via [`docs/README.md`](docs/README.md).
+
+## Components
+
+### Document Editor (`@beyondwork/docx-react-component`)
+
+A fidelity-first React `.docx` editor centered on `WordReviewEditor`. Built for legal review, contract negotiation, and any workflow where documents need to survive a round-trip through Microsoft Word without damage.
+
+**Shipped capabilities:**
+- Full tracked-change and comment support (add, resolve, accept, reject) — including Lane 7b X4.a/X4.b container + range revision markers and move-promotion
+- Suggesting mode where every edit automatically becomes a tracked change
+- Round-trip OOXML preservation — open, edit, export, reopen in Word without repair prompts; preserve-first unknown handling (Lanes 7b/7c closed)
+- Workflow overlays with scope-based editing constraints, marker-backed scope identity, and three-way scope-source discrimination (marker-backed / overlay-only / detached)
+- Runtime-backed read models for document structure, review state, selection, compatibility, and fields
+- Document comparison with LCS-based diffing and redline export
+- Legal document analysis (bookmarks, cross-references, defined terms, signature blocks)
+- Real-time collaboration via Yjs — Lane 4 Phase C shipped (R1 remote-replay coalescing, R3 idle-priority abort signal, pairRuntimes migration)
+- Layout engine proven at **97.77%** (615/629) external layout-structure truth and **96.34%** (606/629) rendered-word geometry over the CCEP contract corpus (see [`services/truth-baseline/`](services/truth-baseline/))
+- Charts v1 — native SVG renderer for 7 chart families with progressive time-slicing (Lane 5 Stages 0–6 shipped)
+- Debug substrate Phase 0 + Phase 1 — runtime projector + 12-channel `TelemetryBus` + `DebugInspectorSnapshot` + `UxResponse` event stream
+- Additive V3 public surface — `createApiV3(runtime)` with Runtime + AI API split, 31 functions under a 4-status taxonomy (`live` / `live-with-adapter` / `partial` / `mock`); Phase P' closed 2026-04-21
+
+**Human-AI parity in practice:**
+- The human clicks "Add Comment" on selected text; the agent calls `ref.addComment({ anchor, body })` (V1) or `api.runtime.review.resolveComment(...)` (V3) on the same selection
+- The human reviews tracked changes in the sidebar; the agent reads `getTrackedChanges()` (V1) or `api.runtime.review.getChanges()` (V3) and makes the same accept/reject decisions
+- The human exports via toolbar; the agent calls `exportDocx()` (V1) or `api.runtime.document.export()` (V3) after the same compatibility check
+- Workflow overlays constrain both humans and agents identically — `getInteractionGuardSnapshot()` / `api.runtime.workflow.getGuard()` is the single source of posture truth
+- The AI action policy module gates 37 discrete agent operations with risk classification and context validation
+- Every `uiVisible` V3 function emits exactly one `UxResponse` event on the `api` telemetry channel — the stream the Phase Q debug UX consumes to render mock-or-live visual traces identically
+
+### Workblocks
+
+Composable task modules that automate business processes. Each workblock is a self-contained package of Python backend logic, React UI components, and a declarative task graph defined in `manifest.yaml`. They execute on the Beyond Work platform via Temporal workflows.
+
+**Categories:**
+- **Document processing** — invoice extraction, PDF template OCR, bulk processing, email-to-action
+- **AI agents** — explore, flow debugging, data querying, task launching, authoring
+- **Analytics** — execution history, company insights, timeline queries
+- **Learning** — human correction capture, learning set curation, embedding management
+- **Infrastructure** — registry, health checks, credential management (9 types)
+
+**Human-AI parity in practice:**
+- Users create workblocks through VS Code Studio with prompts and visual editing; authoring agents create them through the same manifest schema and file tools
+- Users validate invoice fields in a React form; agents validate the same fields through typed task inputs/outputs
+- Both humans and agents operate within the same workblock execution engine — same task graph, same data flow, same error handling
+
+## The Beyond Work Runtime
+
+These components plug into a four-layer platform:
+
+```
+User-Facing (Layer 4)
+  neui (Next.js 15), bport (BFF), MCP server, VS Code extension
+       |
+Workblocks (Layer 3)
+  20+ composable task modules: agents, data processing, credentials
+       |
+Platform Services (Layer 2)
+  bworker (Go), modelproxy (LiteLLM), registry, pythonworker, Temporal
+       |
+AWS Infrastructure (Layer 1)
+  EKS, Crossplane, Terraform, PostgreSQL, Redis, Qdrant, S3, SQS
+```
+
+The document editor lives at Layer 4 as an embeddable surface. Workblocks live at Layer 3 and are orchestrated by the platform. Both expose their capabilities symmetrically to human UIs and agent APIs.
+
+## Shipped vs Coming
+
+The shipped contract today is docx-first. The table below delineates what is ready to build on vs what is planned end-state work. For the full migration narrative, see [`docs/architecture/00-overview.md`](docs/architecture/00-overview.md) §"Migration Plan" (Phases 0–7).
+
+| Area | Shipped today | Coming |
+|---|---|---|
+| Package runtime | `docx` — the only shipped runtime contract | `xlsx` planned; `pdf` future work outside current package boundary |
+| Public API | V1 flat-method `WordReviewEditorRef` (`public-stable`) + V2 facet projections + dual-error `EditorDiagnostic` (`advanced-supported`) + V3 `createApiV3(runtime)` Runtime + AI split (`advanced-supported`; Phase P' 2026-04-21) | V3 UI API surface (Phase 3 remainder); semantic scope compiler (Phase 4); replacement-scope lifecycle (Phase 5); semantic-scope-first AI layer (Phase 6) |
+| Middle stack | Canonical model (`src/model/canonical-document.ts`); runtime core (`src/runtime/document-runtime.ts`); layout engine (`src/runtime/layout/**`); render kernel MVP (`src/runtime/render/**`) | Formal `src/session/**` package/session boundary (Phase 1); formatting semantics layer (Phase 2); explicit geometry projection layer (Phase 2); semantic scope compiler (Phase 4) |
+| Layout / geometry | External truth baseline proven at 97.77% layout / 96.34% rendered-word on 629 CCEP docs | First-class runtime-owned geometry contract for caret/hit-test/replacement envelopes |
+| Debug substrate | Runtime projector + `TelemetryBus` (12 channels, 8 active/wired, 4 reserved) + `DebugInspectorSnapshot` + `UxResponse` stream + `wrapRefForTelemetry` (Phase 0 + Phase 1 shipped 2026-04-20) | `services/debug/` Railway HTTPS service (Phase 2 in progress); MCP proxy + dev-drawer retarget (Phase 3 planned); Phase Q debug UX at `src/ui-tailwind/debug/**` |
+| External oracles | OpenXML SDK validator MCP (round-trip proof); LibreOffice-backed `services/truth-baseline` for layout + geometry; visual-smoke MCP for CCEP templates | Phase F full oracle integration: stage-token lineage, alignment keys, known-divergence register, deterministic environment |
+| BW / CLM integration | Stateless DOCX runtime service at `vendor/beyondwork/`; Yjs transport; timeline/audit substrate | Grouped service families aligned with Runtime/AI API (Phase 7); scope-native CLM primitives replacing raw `blob_ref` + `story/start/end` glue |
+
+The shipped primitives are correct for their respective layers; the target architecture widens the middle and tops the stack, without replacing anything below.
 
 ## Install
 
 ```bash
-pnpm add @beyondwork/docx-react-component
+pnpm add @beyondwork/docx-react-component react react-dom tailwindcss \
+  prosemirror-commands prosemirror-keymap prosemirror-model \
+  prosemirror-state prosemirror-tables prosemirror-transform prosemirror-view
+```
+
+Current packaging truth:
+
+- the package is ESM-only
+- exports point at shipped TypeScript source entry points
+- `types` and subpath `types` entries resolve to the shipped source-backed TypeScript contracts
+- consumers need a bundler or runtime that can resolve `.ts` and `.tsx` ESM imports
+- consumers should import `@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css` once and provide a Tailwind v4 CSS pipeline for it
+- package and source identifiers remain docx-first until a deliberate rename lands
+
+## Shipped Product
+
+The primary shipped surface is:
+
+```tsx
+import { WordReviewEditor } from "@beyondwork/docx-react-component";
+
+<WordReviewEditor />
+```
+
+`WordReviewEditor` remains uncontrolled by default:
+
+- host passes `initialDocx`, `initialSessionState`, or `initialSnapshot`, or provides `hostAdapter.load()` / `datastore.load()`
+- runtime owns the live working session
+- host receives events, warnings, errors, session state, compatibility snapshots, and exported artifacts
+
+Persistence direction:
+
+- `EditorSessionState` is the canonical host-facing live-session contract
+- `EditorHostAdapter` is the preferred persistence boundary for `load`, `saveSession`, `saveExport`, and telemetry
+- `EditorDatastoreAdapter` remains the legacy snapshot bridge for hosts that still persist `PersistedEditorSnapshot`
+
+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 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`
+- V3 public API (additive, Phase P' 2026-04-21):
+  - `@beyondwork/docx-react-component/api/v3` — `createApiV3(runtime)` + metadata primitives + `UxResponse`
+- 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`](docs/reference/public-api.md) + `docs/reference/public-api.manifest.json` for the V1/V2 contract inventory, and [`docs/reference/public-api-3.md`](docs/reference/public-api-3.md) for the V3 surface. Stability guidance for each V3 namespace is in the `docs/wiki/api-v3.md` page (reached via `docs/README.md`).
+
+## Product Contract
+
+For every component this repo ships, the standard is:
+
+> Open -> edit -> save -> reopen in the host application without damage.
+
+For the current shipped `docx` implementation, that specifically means:
+
+- open in recent Microsoft Word without repair prompts
+- preserve supported content and review structures
+- preserve unsupported but preservable OOXML
+- remain editable in Word after export
+
+For the normative API and host contract, use:
+
+- [`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)
+
+## Documentation Map
+
+### Start Here
+
+- [`docs/README.md`](docs/README.md)
+
+### Main Consumer Path
+
+- [`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) — V1 + V2 canonical contract
+- [`docs/reference/public-api-3.md`](docs/reference/public-api-3.md) — V3 Runtime + AI API (additive)
+- [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
+- [`docs/reference/glossary.md`](docs/reference/glossary.md)
+
+### Architecture & Mental Model
+
+- [`docs/architecture/00-overview.md`](docs/architecture/00-overview.md) — target end-state: 11-layer stack, Runtime/AI/UI API split, semantic-scope compiler, Phase 0–7 migration plan
+- `docs/wiki/runtime-truth.md` — canonical-truth narrative: package > model > runtime > PM view, inverted-PM model, 10 perf invariants (navigate via [`docs/README.md`](docs/README.md))
+- `docs/wiki/future-architecture.md` — forward-looking design anchors + proof status
+
+### Wrapper And Agent Path
+
+- [`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) — V1 + V2
+- [`docs/reference/public-api-3.md`](docs/reference/public-api-3.md) — V3
+- [`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/glossary.md`](docs/reference/glossary.md)
+- [`docs/reference/editor-integration-style.md`](docs/reference/editor-integration-style.md)
+- [`docs/reference/ui-theming-and-styling.md`](docs/reference/ui-theming-and-styling.md)
+- [`docs/reference/beyondwork-runtime-environment.md`](docs/reference/beyondwork-runtime-environment.md)
+
+Wrapper and agent docs stay on `main`, but they are downstream integration guidance rather than the canonical package contract.
+
+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
+- V3 is additive — React editor mounts keep using V1/V2; V3 is for stateless services, out-of-process agents, workblocks, and debug consumers
+- `ai.*` mutations (`resolveReference`, `getScopeBundle`, `proposeReplacementScope`, `validateReplacementScope`, `applyReplacementScope`, `attachExplanation`, `createIssue`) are **mock today** pending Phase 4 (scope compiler) and Phase 5 (replacement lifecycle) — the shape is stable, the behavior will be replaced
+
+### Maintainer Path
+
+- [`docs/maintainers/README.md`](docs/maintainers/README.md)
+- [`docs/ccep-contract-templates/README.md`](docs/ccep-contract-templates/README.md)
+- [`docs/plans/README.md`](docs/plans/README.md) — current plans/audits router + archived execution history
+
+The CCEP corpus is kept on `main` as a maintainer-safe smoke-doc source set for agreement-heavy validation and wrapper or agent benchmarking.
+
+### Plans and audits
+
+`docs/plans/` now keeps only the maintainer-facing artifacts that are still in
+scope for current audit/debug work:
+
+- `chrome-composition-audit.md`
+- `chrome-component-index.json`
+- `ux-inventory.md`
+- `scope-audit.md` + `scope-audit-classification.json`
+- `debug-tooling-v2-architecture.md`
+- `doc-debug-stack.md`
+- `doc-debug-test-protocol.md`
+
+Closed lane and one-off execution plans now live under
+`docs/plans/archived/`. The `gap-analysis/` and `v2/`
+subdirectories remain only where current docs or generators still depend on
+them. (The former `lane-prompts` subdirectory was deleted on 2026-04-21;
+its content was consolidated into `docs/wiki/shipped-history.md`.)
+
+### Technical Wiki
+
+[`docs/wiki/`](docs/wiki/) is the feature-by-feature technical layer (40+ topics covering OOXML, ProseMirror, runtime, debug, and platform). Enter via [`docs/README.md`](docs/README.md). Highlights:
+
+- `api-v1` · `api-v2` · `api-v3` — the three public API generations, delineated
+- `runtime-truth` — the canonical-truth narrative every agent should internalize
+- `debugging` + `doc-debug-service-guide` — runtime debug substrate + HTTPS debug service
+- `chrome-composition` + `chrome-composition-backlog` — UX composition audit split: shipped vs outstanding
+- `testing-and-fixtures` — F01–F52 corpus + CCEP 629-doc corpus + truth-baseline numbers + MCP tooling map
+
+## Agent Integration
+
+Agents consume the editor through a consistent pipeline. Two entry shapes, same pipeline:
+
+**V1/V2 ref (React editor mounts):**
+```
+inspect --> locate --> mutate --> validate --> export
+```
+
+**V3 `createApiV3(runtime)` (stateless services, workblocks, out-of-process agents):**
+```
+inspect --> listScopes --> getScopeBundle --> propose --> validate --> apply --> export
+                                              └── mock today (Phase 4/5) ──┘
+```
+
+Beyond Work platform agents extend the V1/V2 pipeline with propose/approve gates:
+```
+inspect --> locate --> propose --> approve --> mutate --> validate --> export
 ```
 
-Peer dependencies: `react` ≥ 19.2, `react-dom` ≥ 19.2, the ProseMirror family (`prosemirror-state`, `prosemirror-view`, `prosemirror-model`, `prosemirror-transform`, `prosemirror-keymap`, `prosemirror-commands`, `prosemirror-schema-basic`), `tailwindcss` ≥ 4.2, and `yjs` + `y-protocols` for collaboration. See `package.json > peerDependencies`.
+The package exposes purpose-built read models — not a monolithic state dump. V1 getters and V3 equivalents dispatch through the same runtime:
+
+| Read model | V1 getter | V3 equivalent | Purpose |
+|---|---|---|---|
+| Document surface | `getRenderSnapshot()` | (composed via `runtime.content.*`) | Structure, blocks, text, selection |
+| Comments | `getComments()` | `api.runtime.review.getComments()` (partial) | Thread state, resolution, anchors |
+| Tracked changes | `getTrackedChanges()` | `api.runtime.review.getChanges()` (partial) | Revision inventory, actionability |
+| Workflow scope | `getWorkflowScopeSnapshot()` | `api.runtime.workflow.queryScopes()` (live) | Scope boundaries, work items, mode |
+| Interaction guard | `getInteractionGuardSnapshot()` | `api.runtime.workflow.getGuard()` (live) | Effective mode, blocked reasons |
+| Compatibility | `getCompatibilityReport()` | `api.runtime.document.validate()` (live-with-adapter) | Export risk assessment |
+| Warnings | `getWarnings()` | (bundled into `validate()`) | Active fidelity or mutation warnings |
+| Layout | `ref.layout.getPage(...)` | `api.runtime.layout.getPage(...)` (live-with-adapter) | Page/block layout reads |
+| Debug snapshot | `runtime.debug.getSnapshot()` | same (shared projector) | Canonical/workflow/review/scope/layout one-shot JSON |
+
+Agents should read the narrow snapshot that answers the next question, not pull the full render snapshot for every decision. Every V3 `uiVisible` call emits exactly one `UxResponse` on the `api` telemetry channel — subscribe via `docs/wiki/debugging.md` (navigate through `docs/README.md`) for mock-or-live traces.
+
+## 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
+- 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
+
+## Contribution Rules
+
+- respect the runtime-owned state model
+- do not bypass commands and transactions
+- do not treat the DOM as canonical state
+- do not silently drop unknown OOXML
+- 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 builds backoffice work components where humans and AI agents are first-class peers. Every capability is designed for both audiences from the start — not bolted on for one after the other. The result is tools that are powerful enough for complex enterprise workflows and structured enough that an agent can operate them safely and predictably.
+
+## 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`.
 
-## Quick start — mount the editor
+### Installation
 
 ```tsx
-import { WordReviewEditor } from "@beyondwork/docx-react-component/ui-tailwind";
-import "@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css";
+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);
 
-export function App() {
   return (
     <WordReviewEditor
-      initialDocument={docxBytes}
-      onExport={(bytes) => /* persist */}
+      ref={editorRef}
+      documentId="doc-001"
+      currentUser={{ userId: "u1", displayName: "Alice" }}
+      initialDocx={docxBytes}
+      onEvent={(event) => console.log(event)}
     />
   );
 }
 ```
 
-## Quick start — headless / stateless service
+---
+
+### 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
-import { DocxSession } from "@beyondwork/docx-react-component/session";
-import { createApiV3 } from "@beyondwork/docx-react-component/api/v3";
+// 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
 
-const session = await DocxSession.open(docxBytes);
-const api = createApiV3(session.runtime);
+```tsx
+<WordReviewEditor readOnly={true} ... />
+```
+
+All editing, commenting, and tracked-change commands are blocked. The toolbar is still rendered but all buttons are disabled.
 
-const outline = await api.runtime.document.getOutline();
-const issues = await api.runtime.review.getChanges();
-const bytes = await api.runtime.document.export();
+#### Workspace layout
+
+```ts
+editorRef.current.setWorkspaceMode("canvas"); // continuous scroll
+editorRef.current.setWorkspaceMode("page");   // paginated view
 ```
 
-See [`examples/headless-service/`](examples/headless-service/) for a full stateless consumer.
+---
+
+### Imperative ref
+
+Obtain the ref via `useRef<WordReviewEditorRef>()`:
+
+```tsx
+const editorRef = useRef<WordReviewEditorRef>(null);
+<WordReviewEditor ref={editorRef} ... />
+
+// then:
+editorRef.current?.addComment({ body: "Needs revision" });
+```
 
 ---
 
-## What's shipped
+### 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
 
-**Editing & review**
-- Tracked changes (add, accept, reject, resolve) incl. container + range markers and move-promotion
-- Suggesting mode — every edit automatically becomes a tracked change
-- Comments — anchored, threaded, mention-aware, with presentation/negotiation layer
-- Workflow overlays and scope-based editing guards
-- Document comparison (LCS-backed diffing + redline export)
+```ts
+editorRef.current.scrollToComment(commentId);
+```
 
-**Fidelity**
-- OOXML round-trip — open, edit, export, reopen in Word without repair prompts
-- Preserve-first handling for unknown fragments (opaque preservation)
-- Layout engine — **97.77 %** external layout-structure truth and **96.34 %** rendered-word geometry on the CCEP contract corpus
-- Charts v1 — native SVG renderer for 7 chart families, progressive time-sliced
+#### Open (focus) a comment in the sidebar
 
-**Collaboration**
-- Yjs transport with HMAC-signed awareness, tamper-gating, external-custody round-trip
-- Prerender cache (`prerenderDocument()`) for cold-open parity
+```ts
+editorRef.current.openComment(commentId);
+```
 
-**Automation surface**
-- **V1/V2 ref-method API** — stable React imperative surface on `WordReviewEditorRef`
-- **V3 stateless API** — `createApiV3(runtime)` exposes Runtime + AI families under a `live` / `live-with-adapter` / `partial` / `mock` taxonomy
-- AI action policy — risk-classified gating for 37 discrete agent operations
-- Every `uiVisible` V3 function emits exactly one `UxResponse` on the `api` telemetry channel — the stream the debug surfaces consume
+#### Get all comments
 
-**Accessibility**
-- Keyboard-first, reduced-motion respected, WCAG-audited (audit harness lives outside the shipping snapshot)
+```ts
+const sidebar: CommentSidebarSnapshot = editorRef.current.getComments();
+```
 
-Feature-level status + known gaps: [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md), [`KNOWN_ISSUES.md`](KNOWN_ISSUES.md), [`KNOWN-ISSUES-VISUAL.md`](KNOWN-ISSUES-VISUAL.md).
+```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.
 
 ---
 
-## Architecture
+### 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);
+```
 
-The editor runs ProseMirror in an **inverted model**: PM is a view surface, the runtime owns every mutation, and the canonical truth order is
+#### Reject a single change
 
-1. OOXML package bytes
-2. `CanonicalDocument`
-3. `DocumentRuntime` derived state (formatting, layout, geometry, scopes, review)
-4. `EditorSurfaceSnapshot` + PM state + DOM
+```ts
+editorRef.current.rejectChange(revisionId);
+```
 
-Higher layers are projections of lower layers. Reading the DOM or PM state as truth is a bug.
+#### Accept all pending changes
 
-The 11-layer target architecture — session, canonical document, formatting, layout, geometry, workflow, runtime API, semantic scope compiler, AI API, UI API, presentation — is documented in [`docs/architecture/00-overview.md`](docs/architecture/00-overview.md), with per-layer canonical specs in [`docs/architecture/01-package-session.md`](docs/architecture/01-package-session.md) … [`11-presentation-surfaces.md`](docs/architecture/11-presentation-surfaces.md).
+```ts
+editorRef.current.acceptAllChanges();
+```
+
+#### Reject all pending changes
+
+```ts
+editorRef.current.rejectAllChanges();
+```
+
+#### Scroll to a tracked change
+
+```ts
+editorRef.current.scrollToRevision(revisionId);
+```
 
 ---
 
-## Documentation lanes
+### Export
 
-| Lane | Path | When to start here |
-|---|---|---|
-| Router | [`docs/README.md`](docs/README.md) | Any time — triage into the right lane |
-| Architecture | [`docs/architecture/00-overview.md`](docs/architecture/00-overview.md) | Canonical per-layer target design for the 11-layer stack |
-| Wiki (feature deep-dives) | [`docs/wiki/`](docs/wiki/) | Topic-organized narrative connecting OOXML + PM + implementation + testing |
-| Migration | [`MIGRATION.md`](MIGRATION.md) | Upgrading across major versions |
-| Known issues | [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md), [`KNOWN_ISSUES.md`](KNOWN_ISSUES.md), [`KNOWN-ISSUES-VISUAL.md`](KNOWN-ISSUES-VISUAL.md) | Preview caveats + visual-fidelity gap inventory |
-| Changelog | [`CHANGELOG.md`](CHANGELOG.md) | Release notes |
+```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.
 
 ---
 
-## Development
+### Events
 
-| Command | Purpose |
-|---|---|
-| `pnpm run lint:tsgo` | TypeScript type check |
-| `pnpm test:repo` | Contract + validation test suite |
-| `pnpm run build` | Build the shipped package |
+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;
+}
+```
+
+For a general-purpose "something about comments changed" signal (covering deletions, reply appends, body edits, reopen, and every other mutation — including Yjs-driven mutations that route through the editor's imperative ref), subscribe to `comments_changed`.
+
+#### `comments_changed`
+
+Fired once per commit whenever the runtime's comment snapshot differs from the previous commit. Use this when you render comments in a sibling component and need to know when to re-fetch via `editorRef.current.getComments()`.
+
+```ts
+{
+  type: "comments_changed";
+  documentId: string;
+  changedCommentIds: string[]; // always non-empty
+}
+```
+
+Covers: `addComment`, `deleteComment`, `resolveComment`, `reopenComment`, `addCommentReply`, `editCommentBody`, and any remote-origin mutation that funnels through the same runtime APIs. Does NOT fire on selection/focus changes.
+
+#### `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.
 
-Agent onboarding: [`CLAUDE.md`](CLAUDE.md), [`AGENTS.md`](AGENTS.md).
-Product charters: [`DESIGN-EDITOR.md`](DESIGN-EDITOR.md), [`DESIGN-WORKBLOCK.md`](DESIGN-WORKBLOCK.md).
-Findings log: [`SHIP-LOG.md`](SHIP-LOG.md).
+```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[]; }
+```
 
 ---
 
-## Browser / runtime support
+### Key types
+
+#### EditorAnchorProjection
 
-- Modern evergreen browsers (Chrome, Firefox, Safari, Edge)
-- React 19.2+, Node 22+ for server-side usage
-- No web workers — all time-slicing via `scheduler.yield` / `requestIdleCallback` on the main thread
+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";
+```
 
 ---
 
-## License
+### 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
 
-See [`LICENSE.md`](LICENSE.md). The package is published under the Beyond Work license for use inside the Beyond Work platform and its authorized integrations.
+```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 "comments_changed":
+        console.log("comments changed:", event.changedCommentIds);
+        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();
+```