@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/README.md

@@ -11,993 +11,136 @@ 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)
 
-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.
+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.
 
-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.
+**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.
 
-## 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`](docs/reference/public-api.md), and [`docs/reference/integration-guide.md`](docs/reference/integration-guide.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.
-
-**Capabilities:**
-- Full tracked-change and comment support (add, resolve, accept, reject)
-- Suggesting mode where every edit automatically becomes a tracked change
-- Round-trip OOXML preservation — open, edit, export, reopen in Word without repair prompts
-- Workflow overlays with scope-based editing constraints
-- 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
-
-**Human-AI parity in practice:**
-- The human clicks "Add Comment" on selected text; the agent calls `addComment({ anchor, body })` on the same selection
-- The human reviews tracked changes in the sidebar; the agent reads `getTrackedChanges()` and makes the same accept/reject decisions
-- The human exports via toolbar; the agent calls `exportDocx()` after the same `getCompatibilityReport()` check
-- Workflow overlays constrain both humans and agents identically — `getInteractionGuardSnapshot()` is the single source of posture truth
-- The AI action policy module gates 37 discrete agent operations with risk classification and context validation
-
-### 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.
-
-## Current Package Reality
-
-The shipped contract today is docx-first:
-
-- `docx` is the only implemented and shipped runtime contract
-- `xlsx` is planned work, not part of the current package contract
-- `pdf` remains future work outside the current package boundary
+---
 
 ## Install
 
 ```bash
-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`
-- 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) and `docs/reference/public-api.manifest.json` for the current contract inventory and stability guidance.
-
-## 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)
-- [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
-- [`docs/reference/glossary.md`](docs/reference/glossary.md)
-
-### 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)
-- [`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
-
-### 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) — active development lanes + open-issues register
-
-The CCEP corpus is kept on `main` as a maintainer-safe smoke-doc source set for agreement-heavy validation and wrapper or agent benchmarking.
-
-### Active Development Lanes
-
-Engineering work is organized into 9 lanes (5 active now + 2 later polish + 2 final) — full plan index, status, and worktree map at [`docs/plans/README.md`](docs/plans/README.md). Each lane has a single self-contained doc at `docs/plans/lane-N-<name>.md`:
-
-**Progress snapshot — 2026-04-19 (post PR #189 + #190 + #191 + #192 merged to `main`; Lane 3 split into 3a + 3b on 2026-04-19 deep evening):**
-
-| # | Lane | % to goal | Status summary |
-|---|---|---|---|
-| 1 | [**Editing Foundation**](docs/plans/lane-1-editing-foundation.md) | **65%** | I1–I6 + I3 widening + I4 + S1 + X3 + I8 shipped; I2B / I7 / R.1–R.5 backlog |
-| 2 | [**Render Performance**](docs/plans/lane-2-render-performance.md) | **85%** | All Phases 1.x + 2.2 + 2.4b + 2.5 (A+B) + 2.9 shipped; Tasks 2.1 / 2.3 left |
-| 3a | [**Layout & Render Engine**](docs/plans/lane-3a-layout-render-engine.md) | **45%** | P1–P6 + P8 + P14.a/b/e shipped; P9 (now unblocked) + P10 + P11 + P12 + P14.c/d backlog |
-| 3b | [**OOXML Fidelity & Round-Trip**](docs/plans/lane-3b-ooxml-fidelity.md) | **55%** | V1 + O3 + O4 + O2 (all 4 slices) + V7 closed; 🚨 O8 + L2.c + V6 + V2a/b/c + R3–R5 backlog |
-| 4 | [**Collab + CLM/Vallor**](docs/plans/lane-4-collab-clm-vallor.md) | **80%** | P1–P14 + all P11 sub-bullets + P12 + perf-parity + P13 A/B/C shipped; P15 / P16 / P17 left |
-| 5 | [**Charts (independent)**](docs/plans/lane-5-charts.md) | **30%** | Stages 0–2 shipped (parsers + theme); Stages 3–7 (SVG renderers + pixel-diff) left |
-| 6a | [**Tokens & Theme Foundation**](docs/plans/lane-6a-tokens-theme-foundation.md) | **~25%** | Active (no gate) — canonical token substrate: brand-accent flip, semantic families, scope-tint tokens, chart palette, hex eviction, density + reduced-motion plumbing |
-| 6b | [**Shell & Workspace Chrome**](docs/plans/lane-6b-shell-workspace-chrome.md) | **~15%** | Gated on 6a.S1+S2 — shell header + toolbar + status + alert banner + unsaved modal + collab chrome restyle; mode-dock decommission; TwCommandPalette |
-| 6c | [**Context & Review Surfaces**](docs/plans/lane-6c-context-review-surfaces.md) | **~15%** | Gated on 6a.S1+S2 — selection toolbar + suggestion card + rail + scope + context toolbars + health panel restyle; TwCommentPreview / TwEmptyState / TwShortcutHint |
-| 6d | [**Visual Fidelity**](docs/plans/lane-6d-visual-fidelity.md) | **~20%** | Gated on 6a.S1+S2 + external-lane deps — L8 A/B/C shipped; L8 Phase D + P11 overlays + P7 + P12 + P14 next |
-| 7a | [**Visual Fidelity Register**](docs/plans/lane-7a-visual-fidelity-register.md) | **0%** | LATER (gated on 6a–6d) — V5 covers, V6 REF/PAGEREF, V7 cascade audit |
-| 7b | [**Revision & Redline Completion**](docs/plans/lane-prompts/lane-7b-revision-redline-completion.md) | **✅ CLOSED** | Phases A–N shipped on `lane-7b-revision-redline` (17 commits) — full X4.a parse (container + range markers), X4.b complete (cellIns accept + reject + row-ins/row-del accept + reject), move-promotion (linked-pair atomic accept/reject). Trigger-gated: X4.c + X5 + nested-table row-insertion scope limit. Validator pass handed off to coordinator |
-| 7c | [**Preservation & Format Coverage**](docs/plans/lane-7c-preservation-format-coverage.md) | **0%** | LATER (gated on 6a–6d) — O6 Strict, OLE preserve-only, picture-SDT, w14/kern/VML defer |
-| 7d | [**Platform Hardening & Hygiene**](docs/plans/lane-7d-platform-hardening-hygiene.md) | **0%** | LATER (gated on 6a–6d) — harness-crash-hardening, fastload activation, worktree consolidation |
-| 8 | [**API Ergonomics / Errors / BC**](docs/plans/lane-8-api-ergonomics.md) | **40%** | LATER — Tracks A+C shipped (error catalog + ergonomics fixes); Tracks B+D+E + public-api.md end-to-end refactor remain |
-| 9 | [**Shipping (v2.0.0)**](docs/plans/lane-9-shipping.md) | **0%** | FINAL — API freeze, semver discipline, changelog, telemetry, customer migration guides, doc completeness audit |
-
-**Aggregate v2.0.0 readiness:** ~70% — long poles are Lane 3 O8 + P9/P10, Lane 4 P15/P16/P17, Lane 1 R.1–R.5, Lane 5 Stage 4 SVG renderers (Lane 5 ships on independent v2.x cadence). Detailed task-completeness factor + per-lane backlog inventory in [`docs/plans/coordination-prompt.md`](docs/plans/coordination-prompt.md).
-
-### Technical Wiki
-
-- [`docs/wiki/`](docs/wiki/) — Feature-by-feature technical documentation (25+ topics covering OOXML, ProseMirror, runtime, and platform)
-
-## Agent Integration
-
-Agents consume the editor through a consistent pipeline:
-
-```
-inspect --> locate --> mutate --> validate --> export
-```
-
-Beyond Work platform agents extend this with propose/approve gates:
-
-```
-inspect --> locate --> propose --> approve --> mutate --> validate --> export
+pnpm add @beyondwork/docx-react-component
 ```
 
-The package exposes purpose-built read models — not a monolithic state dump:
-
-| Read model | Getter | Purpose |
-|---|---|---|
-| Document surface | `getRenderSnapshot()` | Structure, blocks, text, selection |
-| Comments | `getComments()` | Thread state, resolution, anchors |
-| Tracked changes | `getTrackedChanges()` | Revision inventory, actionability |
-| Workflow scope | `getWorkflowScopeSnapshot()` | Scope boundaries, work items, mode |
-| Interaction guard | `getInteractionGuardSnapshot()` | Effective mode, blocked reasons |
-| Compatibility | `getCompatibilityReport()` | Export risk assessment |
-| Warnings | `getWarnings()` | Active fidelity or mutation warnings |
-| Fields | `getFieldSnapshot()` | Field posture and refresh state |
-
-Agents should read the narrow snapshot that answers the next question, not pull the full render snapshot for every decision.
-
-## 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`.
-
-### Installation
-
-```tsx
-import {
-  WordReviewEditor,
-  type WordReviewEditorRef,
-  type WordReviewEditorProps,
-  type WordReviewEditorEvent,
-} from "@beyondwork/docx-react-component";
-```
+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`.
 
-### Basic mount
+## Quick start — mount the editor
 
 ```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);
+import { WordReviewEditor } from "@beyondwork/docx-react-component/ui-tailwind";
+import "@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css";
 
+export function App() {
   return (
     <WordReviewEditor
-      ref={editorRef}
-      documentId="doc-001"
-      currentUser={{ userId: "u1", displayName: "Alice" }}
-      initialDocx={docxBytes}
-      onEvent={(event) => console.log(event)}
+      initialDocument={docxBytes}
+      onExport={(bytes) => /* persist */}
     />
   );
 }
 ```
 
----
-
-### 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
+## Quick start — headless / stateless service
 
 ```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.
+import { DocxSession } from "@beyondwork/docx-react-component/session";
+import { createApiV3 } from "@beyondwork/docx-react-component/api/v3";
 
-#### Workspace layout
+const session = await DocxSession.open(docxBytes);
+const api = createApiV3(session.runtime);
 
-```ts
-editorRef.current.setWorkspaceMode("canvas"); // continuous scroll
-editorRef.current.setWorkspaceMode("page");   // paginated view
+const outline = await api.runtime.document.getOutline();
+const issues = await api.runtime.review.getChanges();
+const bytes = await api.runtime.document.export();
 ```
 
----
-
-### Imperative ref
-
-Obtain the ref via `useRef<WordReviewEditorRef>()`:
-
-```tsx
-const editorRef = useRef<WordReviewEditorRef>(null);
-<WordReviewEditor ref={editorRef} ... />
-
-// then:
-editorRef.current?.addComment({ body: "Needs revision" });
-```
+See [`examples/headless-service/`](examples/headless-service/) for a full stateless consumer.
 
 ---
 
-### Comment operations
+## What's shipped
 
-#### Add 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
-addComment(params: AddCommentParams): string
-// returns the new 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
 
-```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;
+**Collaboration**
+- Yjs transport with HMAC-signed awareness, tamper-gating, external-custody round-trip
+- Prerender cache (`prerenderDocument()`) for cold-open parity
 
-// 2. Open your draft UI, let user type a message...
-// 3. On submit:
-const commentId = editorRef.current.addComment({ anchor, body: draftText });
-```
+**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
 
-#### Resolve a comment
+**Accessibility**
+- Keyboard-first, reduced-motion respected, WCAG-audited (audit harness lives outside the shipping snapshot)
 
-```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.
+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).
 
 ---
 
-### Tracked-change operations
+## Architecture
 
-#### Get all tracked changes
+The editor runs ProseMirror in an **inverted model**: PM is a view surface, the runtime owns every mutation, and the canonical truth order is
 
-```ts
-const changes: TrackedChangesSnapshot = editorRef.current.getTrackedChanges();
-```
+1. OOXML package bytes
+2. `CanonicalDocument`
+3. `DocumentRuntime` derived state (formatting, layout, geometry, scopes, review)
+4. `EditorSurfaceSnapshot` + PM state + DOM
 
-```ts
-interface TrackedChangesSnapshot {
-  pendingChangeIds: string[];
-  acceptedChangeIds: string[];
-  rejectedChangeIds: string[];
-  detachedChangeIds: string[];
-  actionableChangeIds: string[];
-  preserveOnlyChangeIds: string[];
-  totalCount: number;
-  revisions: TrackedChangeEntrySnapshot[];
-}
+Higher layers are projections of lower layers. Reading the DOM or PM state as truth is a bug.
 
-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);
-```
+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).
 
 ---
 
-### Export
+## Documentation lanes
 
-```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.
+| 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 |
 
 ---
 
-### Events
-
-All events are dispatched through the single `onEvent` prop. The `type` discriminator narrows the payload.
+## Development
 
-```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.
+| Command | Purpose |
+|---|---|
+| `pnpm run lint:tsgo` | TypeScript type check |
+| `pnpm test:repo` | Contract + validation test suite |
+| `pnpm run build` | Build the shipped package |
 
-```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[]; }
-```
+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).
 
 ---
 
-### 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
+## Browser / runtime support
 
-```ts
-type WorkspaceMode = "canvas" | "page";
-```
+- 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
 
 ---
 
-### 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
+## License
 
-```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();
-```
+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.