@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/research/docx-react-component/React Component Architecture and Front-End Structure Specification for a Word-Compatible Legal Review Editor.md

@@ -1,1112 +0,0 @@
-# React Component Architecture and Front-End Structure Specification for a Word-Compatible Legal Review Editor
-
-## Purpose and architectural goals
-
-This specification defines an implementation-ready architecture for a **self-contained, Word-compatible legal review editor** delivered as **one embeddable React component** with a **single runtime on the main thread** (no Web Workers). The product targets the **core legal review workflow**: structured editing (paragraphs, headings, lists, tables), **comments**, **tracked insertions/deletions**, and **safe `.docx` round-tripping** that opens cleanly in modern Word processors.
-
-The key architectural tension is: **Word fidelity and round-trip safety** vs. **a clean, lightweight “review editor” UX**. DOCX (OOXML) is designed to capture not only final document content but also review artifacts like tracked revisions and annotations. citeturn0search5turn1search9 A compatibility-first design must therefore treat OOXML as the governing truth for import/export semantics (packaging, relationships, revision/comment markup), even if the editor UI intentionally remains minimal. The underlying standard family (ISO/IEC 29500 / ECMA-376) is explicitly aimed at faithfully representing the existing Word document corpus. citeturn1search13
-
-### Architectural goals
-
-**Embedding**
-- One public React component (`<WordReviewEditor />`) that can be dropped into any host React app without requiring the host to manage internal document state during editing.
-- Host integrates via typed props, callbacks, and an imperative ref API.
-
-**Internal modularity without breaking the “single component” constraint**
-- Package publishes one component entry point, but internally is split into clear modules (schema, commands, import/export, preservation, UI).
-- The editor runtime is framework-agnostic; React subscribes to it (and renders UI) without owning document truth.
-
-**Main-thread correctness and responsiveness**
-- No workers means the architecture must avoid main-thread stalls by:
-  - incremental transactions (never full reparse/re-export on keystrokes),
-  - staged import/export pipelines with explicit yielding,
-  - render minimization and virtualization for side panels.
-
-**Compatibility-first Word support**
-- Import from `.docx` that is an OPC package: parts, relationships, and content types. citeturn0search4turn0search18
-- Export `.docx` with correct OPC structure and canonical WordprocessingML patterns for comments and tracked changes. citeturn0search4turn5search0turn4search0
-- **Unsupported OOXML is never silently dropped**:
-  - preserve whole parts untouched where possible,
-  - preserve unknown elements/markup compatibility constructs,
-  - lock unsupported regions in the editor and generate explicit warnings.
-
-**Maintainability & testability**
-- All edits go through **commands → transactions**.
-- Canonical model updates are deterministic and testable.
-- Import/export, preservation, validation, and command logic are separable from React and can be unit-tested.
-
----
-
-## Public component contract
-
-### Component name and responsibilities
-
-**Public component:** `WordReviewEditor`
-
-**Responsibilities owned by the component**
-- Owns the full editing session: runtime, canonical document state, review state, undo/redo, selection model, and view lifecycle.
-- Loads `.docx` or a persisted snapshot, renders the editor UX, accepts user input, and produces:
-  - JSON snapshots for persistence,
-  - `.docx` exports for Word compatibility.
-- Emits structured events, warnings, and errors.
-- Runs internal autosave using a generic datastore adapter (optional) and/or host-provided callbacks.
-
-**Responsibilities owned by the host app**
-- Provides a document identity, initial document source (docx bytes or snapshot), and optionally a persistence adapter.
-- Supplies authentication/authorization, user identity, and any business rules for “can comment / can edit / can accept changes”.
-- Renders surrounding application UI (routing, page chrome).
-- Stores checkpoints/exports (if adapter is provided) and handles backend failures surfaced by the editor.
-
-### Controlled vs uncontrolled usage
-
-The component is **uncontrolled by default**:
-- Host provides `initialDocx` or `initialSnapshot`.
-- Editor owns working state internally.
-- Host receives change events and snapshots for persistence.
-
-A “controlled” mode is supported only as **replace-on-change**:
-- Host may pass `externalDocumentRevision` and `externalDocSource`.
-- When the revision changes, the editor tears down and reloads the new document source.
-- The host does **not** stream keystrokes back into `value` props.
-
-### TypeScript public interfaces
-
-```ts
-// Public: primary component props
-export interface WordReviewEditorProps {
-  // Identity & user
-  documentId: string;
-  currentUser: EditorUser;
-
-  // Initial content (exactly one should be provided for first load)
-  initialDocx?: Uint8Array | ArrayBuffer;           // .docx bytes
-  initialSnapshot?: PersistedEditorSnapshot;        // canonical JSON resume
-  initialSourceLabel?: string;                      // optional UI label (e.g., "Contract v3")
-
-  // Permissions & mode
-  readOnly?: boolean;                               // disables editing commands
-  reviewMode?: "editing" | "review";                // default "review"
-  markupDisplay?: "clean" | "simple" | "all";        // default "simple"
-
-  // Persistence integration (optional)
-  datastore?: EditorDatastoreAdapter;
-  autosave?: AutosaveConfig;
-
-  // Host integration hooks
-  onEvent?: (e: WordReviewEditorEvent) => void;
-  onWarning?: (w: EditorWarning) => void;
-  onError?: (err: EditorError) => void;
-
-  // Theming & styling
-  theme?: Partial<EditorThemeTokens>;
-  className?: string;
-  style?: React.CSSProperties;
-  styleIsolation?: "scoped" | "shadowRoot";         // default "scoped"
-
-  // Extension slots (strictly UI-level; no arbitrary plugin code in v1)
-  slots?: Partial<EditorSlots>;
-}
-
-// Public: imperative ref API
-export interface WordReviewEditorRef {
-  // Lifecycle
-  focus(): void;
-  blur(): void;
-
-  // Core editor capabilities
-  undo(): void;
-  redo(): void;
-
-  // Comments API
-  addComment(params: AddCommentParams): string;      // returns commentId
-  openComment(commentId: string): void;
-  resolveComment(commentId: string): void;
-
-  // Tracked changes API
-  acceptChange(changeId: string): void;
-  rejectChange(changeId: string): void;
-  acceptAllChanges(): void;
-  rejectAllChanges(): void;
-
-  // Import/export
-  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
-  getSnapshot(): PersistedEditorSnapshot;
-
-  // Diagnostics
-  getCompatibilityReport(): CompatibilityReport;
-  getWarnings(): EditorWarning[];
-}
-
-// Public: user identity
-export interface EditorUser {
-  userId: string;
-  displayName: string;
-  initials?: string;
-}
-
-// Public: autosave configuration
-export interface AutosaveConfig {
-  enabled: boolean;
-  debounceMs: number;            // e.g., 1500
-  maxIntervalMs: number;         // e.g., 15000 (save at least this often if dirty)
-  idleOnly?: boolean;            // if true, prefer idle periods
-}
-
-// Public: datastore adapter (generic persistence API)
-export interface EditorDatastoreAdapter {
-  // Load latest persisted state. Used when host renders editor without providing initialDocx/snapshot.
-  load(params: { documentId: string }): Promise<LoadResult>;
-
-  // Save editor snapshot (fast, JSON). Called for autosave checkpoints and explicit saves.
-  saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult>;
-
-  // Save/export docx artifact (slower, binary).
-  saveExport(params: SaveExportParams): Promise<SaveExportResult>;
-
-  // Optional: host telemetry sink
-  logEvent?(e: EditorTelemetryEvent): void;
-}
-
-// Public: warning/error payloads
-export interface EditorWarning {
-  code:
-    | "unsupported_ooxml_preserved"
-    | "unsupported_ooxml_locked"
-    | "export_roundtrip_risk"
-    | "import_normalized"
-    | "large_document_degraded"
-    | "font_substitution"
-    | "image_missing";
-  message: string;
-  severity: "info" | "warning";
-  details?: Record<string, unknown>;
-  affectedRange?: EditorRangeRef;   // optional anchor into document
-}
-
-export interface EditorError {
-  code:
-    | "import_failed"
-    | "export_failed"
-    | "package_corrupt"
-    | "validation_failed"
-    | "datastore_failed"
-    | "internal_invariant";
-  message: string;
-  isFatal: boolean;
-  details?: Record<string, unknown>;
-}
-
-// Public: event stream (single hook, strongly typed union)
-export type WordReviewEditorEvent =
-  | { type: "ready"; documentId: string; stats: DocumentStats }
-  | { type: "dirty_changed"; dirty: boolean }
-  | { type: "selection_changed"; selection: SelectionSnapshot }
-  | { type: "comment_added"; commentId: string }
-  | { type: "comment_resolved"; commentId: string }
-  | { type: "change_accepted"; changeId: string }
-  | { type: "change_rejected"; changeId: string }
-  | { type: "autosave_state"; state: AutosaveState }
-  | { type: "export_completed"; result: ExportResult };
-
-export interface SaveSnapshotParams {
-  documentId: string;
-  snapshot: PersistedEditorSnapshot;
-  isAutosave: boolean;
-}
-
-export interface SaveExportParams {
-  documentId: string;
-  docx: Uint8Array;
-  compatibilityReport: CompatibilityReport;
-}
-
-export interface LoadResult {
-  snapshot?: PersistedEditorSnapshot;
-  docx?: Uint8Array;
-  sourceLabel?: string;
-}
-
-export interface ExportDocxOptions {
-  // export policy: if unsupported content is preserved but locked, export should still succeed
-  // but may include warnings in the compatibility report
-  includeCompatibilityReport?: boolean;
-}
-
-export interface ExportResult {
-  docx: Uint8Array;
-  compatibilityReport: CompatibilityReport;
-  warnings: EditorWarning[];
-}
-
-// Public: snapshot and compatibility report
-export interface PersistedEditorSnapshot {
-  snapshotVersion: 1;
-  documentId: string;
-  createdAtIso: string;
-  editorBuild: string;
-
-  canonical: CanonicalSnapshot;
-  review: ReviewSnapshot;
-  preservation: PreservationSnapshot;
-}
-
-export interface CompatibilityReport {
-  reportVersion: 1;
-  generatedAtIso: string;
-
-  // Key invariants and risks
-  canRoundTripToWord: boolean;
-  riskLevel: "low" | "medium" | "high";
-
-  // Unsupported or locked features encountered
-  preservedParts: Array<{ partName: string; reason: string }>;
-  lockedRanges: Array<{ reason: string; range: EditorRangeRef }>;
-  notes: string[];
-}
-
-// Minimal range anchor reference usable outside runtime
-export interface EditorRangeRef {
-  anchorPath: string;  // stable anchor token (see internal anchoring spec)
-}
-```
-
-**React-to-runtime contract:** The component uses an external store subscription pattern (subscribe/getSnapshot) so the runtime is not React-dependent; React’s official hook for this pattern is `useSyncExternalStore`. citeturn0search3
-
----
-
-## Internal runtime and module architecture
-
-### Internal layers and boundaries
-
-This editor is published as a single component package, but internally built from modular layers. The key is that **the runtime owns the canonical truth**, and the UI is a projection.
-
-**Layer overview (single runtime, modular internals)**
-
-| Layer | React-bound? | Responsibilities | Must not do |
-|---|---:|---|---|
-| Public React shell (`react/WordEditor`) | Yes | Host integration, layout, toolbars/sidebars, focus orchestration, theming, event wiring | Own canonical truth |
-| Runtime/controller (`runtime/DocumentRuntime`) | No | Orchestrate load/import/export, command dispatch, transaction commit, undo/redo, scheduling, subscriptions | Render UI directly |
-| Canonical state store (`core/state`) | No | Canonical document state, schema, style catalog, numbering, media refs | Touch DOM |
-| Review state store (`core/review`) | No | Comments, threads, anchors, tracked changes metadata, author registry | Store host UI state |
-| Import pipeline (`import/*`) | No | OPC open, OOXML parse, normalization, canonical model build, preservation capture, validation report | Block UI thread without yielding |
-| Export pipeline (`export/*`) | No | Incremental OOXML generation/patching, OPC packaging, relationship & content type updates, validation | Drop unsupported content silently |
-| Preservation layer (`preserve/*`) | No | Store untouched parts, unknown elements, markup-compatibility constructs, opaque blocks | Pretend unsupported is supported |
-| Validation layer (`validate/*`) | No | Structural checks, Word risk detection, compatibility report | Re-parse full doc on keystrokes |
-| UI render layer (`ui/*`) | Yes | Editor surface mount, overlays, sidebars, toolbars, dialogs, virtualization | Mutate canonical state directly |
-| Styling/theme layer (`ui/theme`) | Yes | Token resolution, CSS variables, high-contrast/dark-mode policy | Depend on host global CSS |
-
-### Compatibility-first package model (OPC)
-
-A `.docx` is an Open Packaging Conventions (OPC) package: a collection of **parts** (XML and binary) with **relationships** and a **content types stream** (commonly `[Content_Types].xml`). citeturn0search4turn0search18
-
-**Internal import/export must treat the package as primary**, not just `word/document.xml`. This matters for fidelity-preserving behavior like:
-- preserving untouched parts,
-- keeping relationship IDs stable whenever possible,
-- preserving metadata parts and custom XML,
-- safely adding comments parts or media parts with correct relationships.
-
-### Preservation and markup compatibility
-
-OOXML includes a markup compatibility mechanism and extensibility patterns (e.g., `AlternateContent`) that enable fallback representations. The Open XML SDK documentation describes markup compatibility processing settings and their role in handling such markup. citeturn2search0
-
-**Preservation rule:** if the mapper cannot semantically support some OOXML region, it is **(a)** preserved as an opaque block/part, **(b)** locked in the editor surface, and **(c)** surfaced via warnings.
-
-Unknown OOXML elements must be retained as unknown nodes/structures rather than discarded; Open XML SDK exposes unknown elements explicitly (e.g., `OpenXmlUnknownElement`) as part of the model of “recognized vs. unrecognized standard markup.” citeturn2search1turn2search13
-
-### Recommended internal module structure
-
-The following is the required folder structure. Each module has a strict dependency policy to keep correctness testable and avoid circular UI/runtime coupling.
-
-| Module | Responsibility | Public surface | Allowed deps | Forbidden deps |
-|---|---|---|---|---|
-| `react/WordEditor` | Public component, layout, binds ref API, mounts editor surface | `WordReviewEditor` | `runtime/*`, `ui/*`, `api/*` | `import/*`, `export/*` (call via runtime only) |
-| `runtime/DocumentRuntime` | Orchestrator: load, dispatch, commit, subscriptions, scheduling | `DocumentRuntime` | `core/*`, `import/*`, `export/*`, `preserve/*`, `validate/*`, `api/*` | `ui/*` |
-| `core/schema` | Canonical schema (node/mark types, attributes, invariants) | `schema`, `SchemaVersion` | none | `ui/*`, `react/*` |
-| `core/state` | Canonical state container + selectors | `CanonicalState`, selectors | `core/schema`, `preserve/*` | `ui/*` |
-| `core/commands` | Command registry and implementations | `commands`, `CommandId` | `core/*` | `ui/*`, `react/*` |
-| `core/review` | Review model: comments, changes, authors, anchor remap | `ReviewState`, `reviewSelectors` | `core/state`, `core/selection` | `ui/*` |
-| `core/selection` | Selection representation + mapping utilities | `SelectionModel` | `core/schema`, `core/state` | `ui/*` |
-| `import/opc` | Read OPC zip, list parts, resolve relationships | `openPackage()` | `preserve/*` | `ui/*`, `react/*` |
-| `import/ooxml` | Parse OOXML into intermediate AST with preservation hooks | `parseOOXML()` | `import/opc`, `preserve/*` | `ui/*` |
-| `import/normalize` | Normalize OOXML AST into canonical schema | `normalizeToCanonical()` | `core/schema`, `core/state`, `core/review` | `ui/*` |
-| `export/ooxml` | Generate OOXML from canonical + review state | `buildDocumentXml()` | `core/*`, `preserve/*` | `ui/*` |
-| `export/package` | Write OPC package, update relationships/types | `writePackage()` | `export/ooxml`, `import/opc` | `ui/*` |
-| `preserve` | Preservation store & opaque-block encoding | `PreservationStore` | `core/schema` | `ui/*` |
-| `validate` | Structural/compatibility validation | `validatePackage()`, `validateState()` | `core/*`, `import/opc` | `ui/*` |
-| `ui/editor-surface` | Mounts the editable surface and overlays | `EditorSurface` | `runtime/*`, `ui/theme` | `import/*`, `export/*` |
-| `ui/toolbar` | Toolbar UI + command binding | `Toolbar` | `runtime/*`, `ui/theme` | `core/*` (must call runtime) |
-| `ui/comments` | Comments sidebar, thread UI | `CommentsPanel` | `runtime/*` | direct store mutation |
-| `ui/review` | Changes panel, navigation, accept/reject controls | `ReviewPanel` | `runtime/*` | direct store mutation |
-| `ui/theme` | Tokens → CSS variables, theming policy | `ThemeProvider`, tokens | none | runtime logic |
-| `api` | Public type exports, datastore adapter types | types only | none | runtime internals |
-
----
-
-## Runtime/controller specification
-
-### Runtime as the single orchestrator
-
-The runtime is an in-memory engine that:
-- owns the canonical and review state,
-- applies commands as transactions,
-- emits events,
-- coordinates staged import/export and preservation,
-- exposes subscriptions to UI without React dependency.
-
-React mounts exactly one runtime instance per editor instance.
-
-### Runtime lifecycle: required flows
-
-**Initialization flow**
-1. React shell constructs `DocumentRuntime` with:
-   - documentId, currentUser, mode flags,
-   - datastore adapter (optional),
-   - scheduling strategy (yielding, idle callbacks),
-   - telemetry sink (optional).
-2. Runtime enters `idle` state and exposes subscription API.
-3. React mounts UI and calls `runtime.init()`.
-
-**Document load flow**
-1. Determine source in this precedence order:
-   - `initialSnapshot` prop,
-   - `initialDocx` prop,
-   - `datastore.load(documentId)`.
-2. If snapshot:
-   - validate snapshot version,
-   - hydrate canonical/review/preservation stores.
-3. If docx:
-   - staged import pipeline (OPC → OOXML → normalize → validate → hydrate).
-4. Emit:
-   - `ready` event with stats and initial warnings/warnings panel state.
-
-**Command dispatch flow**
-1. UI triggers `runtime.exec(commandId, payload, origin)`.
-2. Runtime:
-   - resolves command handler,
-   - builds one transaction,
-   - applies transaction atomically,
-   - remaps anchors/review metadata as part of commit,
-   - updates undo/redo stacks,
-   - notifies subscribers, then emits events.
-
-**Save/export flow**
-- **Snapshot save**:
-  - serialize the current in-memory state to `PersistedEditorSnapshot`.
-  - call datastore `saveSnapshot` (if present) and emit autosave events.
-- **Export `.docx`**:
-  - validate state, build compatibility report,
-  - staged export pipeline (generate XML parts + patch preserved package),
-  - return bytes to host and optionally call datastore `saveExport`.
-
-**Autosave flow**
-- Runs only when dirty, and only serializes snapshot (fast path).
-- Uses debouncing plus a max interval, with optional idle scheduling.
-
-**Teardown flow**
-- Remove DOM event handlers for the editor surface.
-- Release large buffers (original package, preserved parts) and clear subscriptions.
-
-### Runtime interfaces
-
-```ts
-export type RuntimePhase =
-  | "idle"
-  | "loading"
-  | "ready"
-  | "exporting"
-  | "error";
-
-export interface RuntimeSnapshot {
-  phase: RuntimePhase;
-  documentId: string;
-  readOnly: boolean;
-  reviewMode: "editing" | "review";
-  markupDisplay: "clean" | "simple" | "all";
-
-  dirty: boolean;
-  canUndo: boolean;
-  canRedo: boolean;
-
-  // Lightweight UI-facing derived state
-  selection: SelectionSnapshot;
-  stats: DocumentStats;
-
-  // Warning/error surfaces
-  warnings: EditorWarning[];
-  fatalError?: EditorError;
-}
-
-export interface RuntimeEventMap {
-  ready: { documentId: string; stats: DocumentStats };
-  dirty_changed: { dirty: boolean };
-  selection_changed: { selection: SelectionSnapshot };
-  warning_added: { warning: EditorWarning };
-  warning_cleared: { code: EditorWarning["code"] };
-  error: { error: EditorError };
-  autosave_state: { state: AutosaveState };
-  export_completed: { result: ExportResult };
-}
-
-export type Unsubscribe = () => void;
-
-export interface DocumentRuntime {
-  init(): Promise<void>;
-
-  // Store subscription (React uses useSyncExternalStore against these)
-  subscribe(cb: () => void): Unsubscribe;
-  getSnapshot(): RuntimeSnapshot;
-
-  // Event subscription (non-React consumers possible)
-  on<K extends keyof RuntimeEventMap>(type: K, cb: (e: RuntimeEventMap[K]) => void): Unsubscribe;
-
-  // Command dispatch
-  exec<TPayload>(commandId: CommandId, payload: TPayload, origin: CommandOrigin): CommandResult;
-
-  // Export and persistence
-  getPersistedSnapshot(): PersistedEditorSnapshot;
-  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
-
-  destroy(): void;
-}
-
-export interface CommandOrigin {
-  source:
-    | "keyboard"
-    | "toolbar"
-    | "context_menu"
-    | "comment_panel"
-    | "review_panel"
-    | "api";
-  timestampIso: string;
-}
-```
-
-**Why external-store subscription:** React’s `useSyncExternalStore` is designed for safely reading/subscribing to an external (non-React) store using a `subscribe` function and a `getSnapshot` function. citeturn0search3
-
----
-
-## State, command, transaction, and event flow
-
-This section defines the internal state decomposition and the mandatory rule: **every mutation happens via commands → transactions → commit**, never direct state mutation.
-
-### State architecture (four buckets)
-
-#### Canonical document state (owned by runtime; participates in undo/redo)
-
-**Contents**
-- Canonical content tree (blocks, inlines).
-- Styles catalog (paragraph/run styles) and style application references.
-- Numbering/list definitions (abstract + instance mapping).
-- Media references (images) and relationship IDs for export binding.
-- Preservation bindings (opaque blocks and preserved-part handles).
-
-**Rules**
-- Immutable snapshots with structural sharing (transaction produces new state referencing old where unchanged).
-- Serialization required (in `PersistedEditorSnapshot.canonical`).
-- Undo/redo must fully restore canonical state.
-
-**OOXML grounding:** WordprocessingML’s core is built from body → paragraphs/runs/text and associated properties. citeturn4search12
-
-#### Review state (owned by runtime; participates in undo/redo for content-affecting actions)
-
-**Contents**
-- Comments: threads, replies, authors, resolved state.
-- Anchors: range anchoring into canonical content.
-- Tracked changes: insertions/deletions and their metadata (author, date, change id).
-- Author registry.
-
-**Rules**
-- Anchors must remap through every transaction.
-- Review state serializes into snapshot `review`.
-- Undo/redo includes:
-  - adding/removing comments and replies,
-  - accept/reject changes,
-  - toggling resolved state,
-  - creation of new tracked changes.
-
-**OOXML grounding:** DOCX explicitly stores review artifacts like tracked changes and threaded comments. citeturn0search5
-
-#### UI/view state (owned by React; does not participate in undo/redo)
-
-**Contents**
-- Sidebar open/closed, selected tab.
-- Hovered entities (comment highlight hover).
-- Context menu open state, dialogs/popovers.
-- Transient toolbar state (e.g., “font menu open”).
-
-**Rules**
-- Must be reconstructible from runtime snapshot + local UI.
-
-#### Persistence/session state (owned by runtime; partially persisted)
-
-**Contents**
-- Dirty flag, save status, autosave status.
-- Import/export warnings and last compatibility report.
-
-**Rules**
-- Dirty flag not persisted (recomputed on load).
-- Compatibility report persisted optionally (recommended for audit/logging).
-- Autosave state not persisted.
-
-### Command and transaction system
-
-This architecture adopts a ProseMirror-like model: transactions apply incremental steps and include **mapping** to update positions and selections. Position mapping is a first-class concept used to keep selections/anchors stable when the document changes. citeturn1search3turn1search0
-
-#### Command interfaces
-
-```ts
-export type CommandId =
-  | "text.insert"
-  | "text.deleteBackward"
-  | "format.toggleBold"
-  | "format.toggleItalic"
-  | "block.setParagraph"
-  | "block.setHeading"
-  | "list.toggleOrdered"
-  | "table.insertRow"
-  | "comment.add"
-  | "comment.resolve"
-  | "change.accept"
-  | "change.reject";
-
-export interface EditorCommand<TPayload = unknown> {
-  id: CommandId;
-  isEnabled(ctx: CommandContext, payload: TPayload): boolean;
-  run(ctx: CommandContext, payload: TPayload): Transaction; // no side effects
-}
-
-export interface CommandContext {
-  canonical: CanonicalState;
-  review: ReviewState;
-  selection: SelectionModel;
-  config: RuntimeConfig;
-  user: EditorUser;
-}
-
-export interface CommandResult {
-  applied: boolean;
-  reason?:
-    | "disabled"
-    | "read_only"
-    | "invalid_selection"
-    | "unsupported_range_locked";
-  transactionId?: string;
-}
-```
-
-#### Transaction interfaces and metadata requirements
-
-```ts
-export interface Transaction {
-  id: string;
-  origin: CommandOrigin;
-
-  // Atomic changes:
-  steps: TransactionStep[];
-  mapping: PositionMapping;   // used to remap anchors and selection
-
-  // Required metadata:
-  createdAtIso: string;
-  affectedRanges: Array<{ from: number; to: number }>;
-  changesReviewState: boolean;
-
-  // For review/tracking:
-  trackChangesMode: "off" | "on";
-  author: EditorUser;
-}
-
-export interface TransactionStep {
-  type: "replace" | "addMark" | "removeMark" | "setNodeAttr" | "insertNode" | "deleteNode";
-  // Step-specific payload omitted here; defined in core/state
-}
-
-export interface PositionMapping {
-  map(pos: number, assoc?: -1 | 1): number;
-  // Optional: mapRange for quick re-anchor of ranges
-  mapRange(from: number, to: number): { from: number; to: number };
-}
-```
-
-**Invariants**
-- Transactions must be deterministic: same input state + payload yields same output state.
-- Every transaction includes a mapping.
-- Anchor remapping **must** run before subscribers are notified.
-- If mapping cannot safely remap an anchor (e.g., anchor deletes the entire region), the anchor transitions to a “detached” state and produces an explicit warning.
-
-### Comments anchoring and compatibility requirements
-
-Word comment anchoring commonly uses:
-- `commentRangeStart` / `commentRangeEnd` to mark the commented range boundaries, and
-- `commentReference` to connect inline content to a comment definition in the comments part. citeturn5search1turn0search6turn5search0
-
-**Internal anchor model**
-- Each comment has a stable `commentId` and an anchor record:
-  - `anchorStart` and `anchorEnd` as positions in the canonical model.
-- The anchor remaps through every transaction mapping.
-- If a user inserts a comment at a caret selection (collapsed), the editor creates a zero-width anchor that expands as text is typed (implementation: range with identical start/end + assoc “stickiness”).
-
-### Tracked changes: internal representation and OOXML grounding
-
-WordprocessingML represents tracked insertions and deletions using revision elements; Open XML SDK exposes these concepts explicitly (e.g., inserted run content `ins`, deleted run content `del`, and `delText` for deleted literal text). citeturn4search0turn4search1turn4search5
-
-**Internal tracked change model**
-- Tracked changes are stored as **marks** (inline) and **node attributes** (block/table row changes):
-  - `change.insert` mark wraps inserted content.
-  - `change.delete` mark wraps deleted content (content retained in model but rendered conditionally).
-- Each mark carries:
-  - `changeId` (stable),
-  - `authorId`, `authorName`,
-  - `dateIso`,
-  - `status: "pending" | "accepted" | "rejected"` (pending is what exports as tracked markup).
-- Document-level tracking is governed by a settings flag; Word defines a `trackRevisions` setting element indicating revisions are tracked. citeturn1search5turn1search21
-
-**Accept/reject behavior**
-- Accept insertion: unwrap inserted mark (content stays, mark removed).
-- Reject insertion: delete the content (with history).
-- Accept deletion: delete the content (remove from canonical model).
-- Reject deletion: unwrap deletion mark (content stays, mark removed).
-
-Microsoft provides guidance on accepting revisions in Open XML documents, reinforcing that revisions are structured markup not “visual styling.” citeturn4search6turn0search1
-
-### Event emission rules
-
-**Two channels**
-1. **Store notification**: synchronous `subscribe()` callbacks fire after commit (for React rerender).
-2. **Typed events**: `runtime.on(type, cb)` emissions fire after store subscribers, and may be async-scheduled for heavy payloads (e.g., compatibility report).
-
-**Hard rules**
-- Store snapshot must always be internally consistent at notification time.
-- Events must carry transaction IDs when relevant.
-- No direct DOM-derived events are allowed to mutate state; DOM is only an input surface.
-
----
-
-## Rendering architecture and front-end UX structure
-
-### Core rendering strategy
-
-The editor surface is composed as:
-- a single, focusable editable region (contenteditable-based),
-- a projection of canonical content,
-- overlays/“decorations” for comments and tracked changes,
-- side panels for review navigation and thread view.
-
-A ProseMirror-style plugin/decorations model is the proven way to represent overlays that remap with document changes, and to keep decoration computation separate from document content. citeturn1search4
-
-**What renders from canonical content**
-- Paragraphs/headings
-- Runs/marks (bold/italic/underline)
-- Lists (ordered/bulleted)
-- Tables (with legal-friendly minimal controls)
-- Opaque blocks (unsupported content placeholders)
-
-**What renders as overlay/decorations**
-- Comment highlight ranges (background + gutter marker)
-- Tracked change highlights (insertion underline + deletion strike styling)
-- Active selection handles
-- Hovered comment/change emphasis
-
-### Editor surface composition (React + non-React boundary)
-
-**React owns**
-- Layout (toolbar, columns, status bar).
-- Panels (comments/review).
-- Popovers (inline formatting menu, comment composer).
-- Theme tokens and CSS variables.
-
-**Editor surface (imperative view) owns**
-- Input event handling (beforeinput/keydown/composition).
-- Translating events → commands.
-- Applying incremental DOM updates based on transactions (not full React rerender per keystroke).
-
-This split is necessary to satisfy:
-- “no full rerender on each keystroke,”
-- correctness for IME/composition,
-- stable selection behavior.
-
-### Minimizing rerenders and maintaining stable identity
-
-**Stable keys**
-- Every block node has a `nodeId` stable across edits (generated at import or node creation).
-- Block components (paragraph/table/list item) are keyed by `nodeId`.
-
-**Subscription granularity**
-- React should subscribe to:
-  - lightweight `RuntimeSnapshot` for top-level UI (dirty, canUndo/canRedo, selection summary),
-  - separate derived selectors for:
-    - comments list,
-    - changes list,
-    - compatibility warnings.
-
-**Memoization rules**
-- Sidebar lists are memoized by item IDs (commentId/changeId).
-- Toolbar state computes from a small selection snapshot, not from full doc.
-
-**Virtualization**
-- Comments panel and changes panel must be windowed (virtualized) when lists exceed a threshold (e.g., >200 entries).
-- Document surface virtualization is **not default** in editable mode; instead, degrade overlay complexity for very large documents (see performance section).
-
-image_group{"layout":"carousel","aspect_ratio":"16:9","query":["Microsoft Word track changes comments sidebar screenshot","minimal rich text editor toolbar tiptap style","Notion editor typing interface","legal document review software interface comments sidebar"],"num_per_query":1}
-
-### UX layout structure
-
-**Layout grid**
-- Top: toolbar (fixed height).
-- Center: document canvas (scroll container).
-- Right: sidebar area (tabs: Comments / Changes), collapsible.
-- Bottom (optional): status bar (save state, warnings).
-
-**Modes**
-- **Read-only**: disables editing commands; allows comment browsing and change navigation; selection still allowed.
-- **Review mode**: defaults to showing comments/changes; markup display switch visible.
-- **Markup display**
-  - `clean`: hide deletions, show accepted content view; comments shown as markers in margin only.
-  - `simple`: insertions shown, deletions collapsed with indicator; comment highlights subtle.
-  - `all`: full redlines, deletion strikethrough, full highlight overlays.
-
-**Unsupported-content states**
-- Opaque blocks display a locked placeholder card:
-  - icon, short label (e.g., “Unsupported field code”),
-  - “Preserved for Word round-trip” subtext,
-  - optional “Show details” popover listing the OOXML element/part and risk level.
-- Editing actions within opaque blocks are blocked with a non-fatal warning.
-
-**Loading/error states**
-- Loading: skeleton canvas + “Importing document…” with staged progress labels.
-- Fatal import error: full-page error inside component with “Download original” (if provided) and diagnostics token in details.
-
----
-
-## Front-end styling, design system, and accessibility specification
-
-### Styling system goals
-
-- Polished, modern, restrained; optimized for long review sessions.
-- TipTap/Notion-like calm tooling, not ribbon UI.
-- Host-safe embedding via scoped CSS variables (or optional ShadowRoot).
-
-### Theme tokens (required)
-
-Tokens are implemented as CSS variables rooted under `.wre-root` (or inside ShadowRoot if enabled). The component exposes `theme` overrides that map 1:1 to tokens.
-
-```ts
-export interface EditorThemeTokens {
-  // Typography
-  fontFamilyUi: string;           // e.g., "Inter, system-ui, sans-serif"
-  fontFamilyDoc: string;          // e.g., "Times New Roman, serif" or host-provided
-  fontSizeUiPx: number;           // e.g., 13
-  fontSizeDocPx: number;          // e.g., 12
-  lineHeightUi: number;           // e.g., 1.35
-  lineHeightDoc: number;          // e.g., 1.5
-
-  // Spacing scale
-  space1: number; // 4
-  space2: number; // 8
-  space3: number; // 12
-  space4: number; // 16
-  space5: number; // 24
-
-  // Radius & elevation
-  radiusSm: number; // 6
-  radiusMd: number; // 10
-  shadowSm: string;
-  shadowMd: string;
-
-  // Neutral palette
-  colorBg: string;
-  colorSurface: string;
-  colorSurfaceMuted: string;
-  colorBorder: string;
-  colorText: string;
-  colorTextMuted: string;
-
-  // Accent palette
-  colorAccent: string;
-  colorAccentHover: string;
-  colorAccentTextOn: string;
-
-  // Review colors (must also have non-color indicators; see a11y)
-  colorInsertion: string;
-  colorDeletion: string;
-  colorComment: string;
-
-  // Feedback colors
-  colorWarning: string;
-  colorError: string;
-  colorSuccess: string;
-
-  // Focus ring
-  focusRing: string; // e.g., "0 0 0 3px rgba(...)"
-}
-```
-
-**Usage guidance**
-- Toolbar background uses `colorSurface`; borders use `colorBorder`.
-- Document canvas uses `colorBg`; the “paper” uses `colorSurface`.
-- Insertion/deletion/comment highlights use the review colors but must not be the only indicator (a11y requirement below).
-
-### Dark mode and high contrast policy
-
-- Dark mode is supported via token overrides; no separate CSS.
-- High contrast:
-  - must meet text contrast expectations and avoid color-only meaning.
-  - provide an option `theme.highContrast = true` that increases border and focus visibility and strengthens non-color indicators.
-
-Contrast and non-color meaning requirements align with WCAG guidance for contrast and “use of color.” citeturn3search13turn3search1turn3search5
-
-### Embedding style isolation strategy
-
-**Default (`styleIsolation="scoped"`)**
-- All CSS is scoped beneath `.wre-root`.
-- Document surface uses a controlled subset of CSS reset rules to prevent host CSS leakage.
-
-**Optional (`styleIsolation="shadowRoot"`)**
-- Render inside a ShadowRoot to isolate host CSS.
-- Must still expose theme tokens via CSS variables set on the host element and inherited into shadow.
-
-### Accessibility specification (WCAG-relevant behaviors)
-
-**Keyboard navigation model**
-- **Primary focus order**
-  1. Toolbar (single tab stop using roving tabindex)
-  2. Document surface
-  3. Sidebar tabs
-  4. Sidebar list and thread content
-  5. Status bar (if interactive)
-- Editor shortcuts:
-  - Mod+B/I/U toggles formatting
-  - Mod+Z / Mod+Shift+Z undo/redo
-  - Alt+Shift+M add comment (configurable)
-  - F6 cycles focus between major regions (toolbar ↔ canvas ↔ sidebar)
-
-**Toolbar accessibility**
-- Toolbar container uses `role="toolbar"` with `aria-label="Editor toolbar"`.
-- Implements roving tabindex to reduce tab stops (an explicit benefit called out in ARIA toolbar guidance). citeturn3search0turn3search8turn3search4
-
-**Document surface semantics**
-- Editable region must be announced as an editable text field; one workable approach is `role="textbox"` with `contenteditable="true"` and appropriate `aria-multiline="true"`. citeturn3search6
-- When read-only, keep `contenteditable="true"` but set `aria-readonly="true"` to indicate editability is conceptually present but disabled. citeturn3search6
-
-**Focus management**
-- Must provide a visible focus indicator for all interactive elements and for the editable surface, consistent with Focus Visible expectations. citeturn3search9turn3search5
-- Popovers/dialogs trap focus and restore focus to the invoking control on close.
-
-**Comments and revisions accessibility**
-- Comments and changes lists must be navigable by keyboard:
-  - Up/Down to move between items,
-  - Enter to open/focus thread,
-  - Escape to return to list.
-- Each comment highlight in the document must have:
-  - a non-color cue (e.g., underline style or gutter icon),
-  - an accessible description via `aria-describedby` on the relevant decoration wrapper.
-- Tracked deletions must not rely only on red color; include strikethrough and/or bracket indicators, consistent with “use of color” guidance. citeturn3search1turn3search5
-
-**Reduced motion**
-- Respect `prefers-reduced-motion`; disable animated highlight pulses and smooth scrolling.
-
----
-
-## Performance strategy without Web Workers and persistence integration
-
-### Main-thread performance principles
-
-**What must never happen on each keystroke**
-- Re-import `.docx` or parse XML.
-- Rebuild the full OOXML export.
-- Re-render the entire document via React reconciliation.
-- Recompute all comment/change decorations for the full document if only a small region changed.
-
-**Scheduling primitives and yielding**
-- Use `scheduler.yield()` where available to split long tasks and allow high-priority work (input, rendering) to proceed; this is explicitly intended to keep the main thread responsive. citeturn1search14turn1search18
-- Use `requestIdleCallback` for low-priority work (e.g., rebuild side-panel indexes, run low-cost validations), with a timeout for required work; MDN describes it as a way to run background/low priority work without impacting input latency, but notes limited availability in some browsers. citeturn1search2turn1search22
-
-**Mandatory yielding points**
-- After unzip part listing.
-- After parsing each major XML part (`document.xml`, `styles.xml`, `numbering.xml`, `comments.xml`).
-- After building canonical content for each N paragraphs (chunk size based on file size, e.g., 200–500).
-- During export:
-  - after generating `document.xml`,
-  - after patching relationships and content types,
-  - before final zip compression.
-
-### Staged import pipeline (main-thread safe)
-
-**Stage A: OPC open (fast, chunked)**
-- Read zip central directory.
-- Parse `[Content_Types].xml` and `_rels/.rels` to locate the main document part and related parts; OPC defines parts, relationships, and a content types stream. citeturn0search4turn0search18
-
-**Stage B: OOXML parse to intermediate AST**
-- Build a lightweight AST that:
-  - preserves element names/attributes,
-  - retains unknown elements as “unknown nodes” tied to preservation store.
-
-**Stage C: Normalize to canonical schema**
-- Map supported content:
-  - paragraphs, runs, inline properties,
-  - lists/numbering references,
-  - tables,
-  - comments anchors,
-  - tracked change wrappers.
-- Map unsupported content:
-  - convert to opaque nodes bound to preservation.
-- Emit import warnings for any normalization that changes semantics.
-
-**Stage D: Validate + compatibility report**
-- Structural validation:
-  - required parts present,
-  - basic relationship integrity,
-  - comment/change ID consistency.
-- Output a compatibility report attached to runtime state.
-
-### Staged export pipeline
-
-**Fast path principle:** export only regenerates parts that the editor owns; all other parts are copied verbatim from `PreservedPackage`.
-
-- Regenerate:
-  - `word/document.xml` (content + revision markup),
-  - `word/comments.xml` (if comments exist),
-  - relationship parts that must change (if new parts are introduced).
-- Preserve untouched:
-  - theme parts, custom XML, unused parts, vendor extension parts.
-
-Tracked changes export must use the standard revision markup patterns (inserted/deleted run content and related deletion text conventions). citeturn4search0turn4search1turn4search5  
-Comments export must use the anchor + reference linkage model between range markers and comment definitions. citeturn5search0turn5search1turn0search6
-
-### Large-document degradation policy
-
-**Thresholds (example; must be configurable)**
-- `> 250 pages` or `> 2 MB document.xml`:
-  - disable “all markup” by default (offer toggle with warning),
-  - simplify decoration rendering (only show active/nearby comment highlights),
-  - virtualize sidebar lists aggressively,
-  - defer expensive diagnostics.
-
-**Safe mode behavior**
-- Show banner warning: “Large document: review overlays simplified to keep typing responsive.”
-- Never drop fidelity; simplification is visual-only.
-
-### Performance budgets (legal review acceptable targets)
-
-- Typing latency (p50): ≤ 16 ms; (p95): ≤ 50 ms
-- Selection/arrow navigation: ≤ 30 ms (p95)
-- Initial import (common contract 50–150 pages): ≤ 2–5 s (with visible progress)
-- Export docx (common contract): ≤ 3–6 s (with progress + yielding)
-- Sidebar open/scroll (virtualized): ≤ 16 ms per frame during scroll
-
-### Persistence and datastore integration
-
-**In-memory editing model**
-- Runtime holds the canonical and review state in memory throughout the session.
-- Persistence uses **checkpoints** (JSON snapshot) + **exports** (docx artifact).
-
-**What is persisted**
-- Canonical snapshot (content, styles, numbering, media refs)
-- Review snapshot (comments, changes, authors)
-- Preservation snapshot (preserved parts hashes/handles, opaque regions metadata)
-
-**What is not persisted**
-- DOM state
-- Transient UI state (panels open, hover)
-- Dirty flag (recomputed)
-
-**Recovery/resume**
-- On load, prefer latest snapshot checkpoint over docx if both exist, unless host requests “reimport from docx.”
-
-**Failure behavior**
-- Autosave failures are non-blocking:
-  - show status indicator + retry with exponential backoff,
-  - emit `datastore_failed` errors (non-fatal).
-- Explicit “Save” may be blocking depending on host policy (configurable).
-
----
-
-## Error handling, testability, implementation phasing, non-goals, and quality bar
-
-### Error and warning model (front-end behavior)
-
-| Condition | Internal representation | User-facing treatment | Blocking? |
-|---|---|---|---|
-| Corrupt package / cannot open OPC | `EditorError{code:"package_corrupt", isFatal:true}` | Full error state + allow downloading original bytes if available | Yes |
-| Recoverable import normalization | `EditorWarning{code:"import_normalized"}` | Non-blocking banner + details in compatibility panel | No |
-| Unsupported OOXML preserved | `EditorWarning{code:"unsupported_ooxml_preserved"}` | Banner + list of preserved parts/ranges | No |
-| Unsupported region locked | `EditorWarning{code:"unsupported_ooxml_locked"}` | Inline placeholder + sidebar entry; disallow editing in that region | Partially (range-level) |
-| Export integrity failure | `EditorError{code:"export_failed", isFatal:false}` | Modal “Export failed” with retry; keep session state | No (unless host requires) |
-| Validation failure (state invariant) | `EditorError{code:"internal_invariant", isFatal:true}` | Fatal error with diagnostic token | Yes |
-| Autosave failure | `EditorError{code:"datastore_failed", isFatal:false}` | Status bar error + retry | No |
-
-### Testability requirements
-
-**Framework-agnostic unit tests (must not import React)**
-- `core/schema`: schema invariants, node/mark validation.
-- `core/commands`: command enablement, transaction outputs.
-- `core/review`: anchor mapping through synthetic transactions.
-- `import/*`: fixture-based docx parsing (golden canonical snapshot + preservation snapshot).
-- `export/*`: golden `.docx` generation tests (byte-level comparisons with normalization for timestamps).
-
-**Runtime tests**
-- lifecycle flows (load → edit → autosave → export).
-- subscription correctness (no missed notifications, snapshot consistency).
-
-**React integration tests**
-- keyboard interactions, toolbar and sidebar wiring.
-- focus management and accessible navigation.
-
-**Accessibility tests**
-- automated checks (axe) for role/labeling.
-- keyboard-only interaction flows for:
-  - toolbar roving tabindex,
-  - entering/leaving canvas,
-  - opening comment dialogs.
-
-**Performance smoke tests (CI)**
-- import/export under budget with representative 100+ page fixtures.
-- typing latency checks via synthetic input event harness (threshold-based fail).
-
-### Implementation phasing (exit criteria are mandatory)
-
-**Phase: Shell + runtime skeleton**
-- Scope: public component, runtime interface, subscription wiring, theme tokens scaffold, status bar skeleton.
-- Exit: load stub document, basic focus/blur, emits `ready`.
-
-**Phase: Document surface + basic editing wiring**
-- Scope: editable surface, text insertion/deletion, paragraph model, selection snapshot, undo/redo.
-- Exit: typing works without full rerender; undo/redo stable.
-
-**Phase: Toolbar + comments sidebar**
-- Scope: formatting toggles, add comment flow, comment anchoring, sidebar list + thread view.
-- Exit: comments round-trip through snapshot; anchors remap through edits.
-
-**Phase: Review mode + tracked changes UI**
-- Scope: track changes on/off, insertion/deletion markup rendering, accept/reject per change, changes panel navigation.
-- Exit: exports open in Word with visible tracked changes and comments.
-
-**Phase: Persistence integration**
-- Scope: datastore adapter wiring, autosave, recovery.
-- Exit: autosave checkpoint + explicit export save, robust failure UI.
-
-**Phase: Performance hardening**
-- Scope: staged import/export yielding, sidebar virtualization, large-doc safe mode.
-- Exit: meets performance budgets for representative fixtures.
-
-**Phase: Theming + accessibility polish**
-- Scope: high contrast, dark mode tokens, focus-visible polish, ARIA correctness.
-- Exit: a11y test suite passes; design tokens documented and stable.
-
-### Non-goals
-
-This architecture explicitly does **not** attempt:
-- Full Word ribbon parity or Word layout/pagination parity.
-- Unlimited plugin ecosystem in v1 (extensions are UI slots only).
-- Real-time collaborative editing in v1.
-- Native rendering/editing support for every OOXML feature; unsupported constructs must be preserved/locked/warned, not “best-effort silently flattened.”
-- Macro-enabled documents (`.docm`) support in v1.
-
-### Output quality bar (acceptance criteria)
-
-A build is considered “spec-complete” only if:
-- Every user-visible edit path goes through commands and transactions.
-- Import/export supports `.docx` packaging and produces Word-opening documents without repair warnings for supported feature sets (comments + tracked changes + tables/lists).
-- Unsupported content is preserved and surfaced (never silently dropped).
-- Large documents stay usable on the main thread with documented degradation modes.
-- The public API is stable, typed, and sufficient for host integration and persistence.
-- Core modules are testable without React; React tests cover UX, a11y, and key interaction flows.