@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/README.md

@@ -1,17 +1,19 @@
 ---
-title: React OOXML Office
-summary: Shipped docx package landing page and primary router into consumer, wrapper, agent, and maintainer documentation.
+title: Beyond Work Components
+summary: Backoffice work components landing page and primary router into consumer, wrapper, agent, and maintainer documentation.
 audience: consumer, wrapper, agent, maintainer
 stability: main-path
 docRole: main-path
 canonical: true
 ---
 
-# React OOXML Office
+# Beyond Work Components
 
 [![CI](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml)
 
-`@beyondwork/docx-react-component` is the shipped product in this repository: a fidelity-first React docx editor centered on `WordReviewEditor`.
+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.
+
+The design principle across every component: **advanced tasks should be equally easy for AI agents and human users.** Every capability exposed through the UI is also available through a structured API. Every API is designed so an agent can inspect state, reason about it, and act on it without special accommodation. Humans and agents share the same runtime, the same commands, the same read models, and the same fidelity guarantees.
 
 ## Use This README For
 
@@ -19,11 +21,70 @@ canonical: true
 - installing the package
 - finding the right documentation lane quickly
 
-Do not use this README as the full package contract. The canonical consumer path starts in `docs/README.md`, `docs/reference/public-api.md`, and `docs/reference/integration-guide.md`.
+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 repository may also carry broader branch-local work, but the shipped contract today is still docx-first:
+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
@@ -93,11 +154,11 @@ The current shipped ESM exports include:
   - `@beyondwork/docx-react-component/tailwind`
   - `@beyondwork/docx-react-component/api/public-types`
 
-Use `docs/reference/public-api.md` and `docs/reference/public-api.manifest.json` for the current contract inventory and stability guidance.
+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 format the repo eventually ships, the standard is:
+For every component this repo ships, the standard is:
 
 > Open -> edit -> save -> reopen in the host application without damage.
 
@@ -158,7 +219,38 @@ Current integration honesty:
 
 The CCEP corpus is kept on `main` as a maintainer-safe smoke-doc source set for agreement-heavy validation and wrapper or agent benchmarking.
 
-Maintainer prompts, operator runbooks, and proof/closure material remain important, but they are not the first reading path for package consumers.
+### 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
+```
+
+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
 
@@ -181,9 +273,7 @@ Maintainer prompts, operator runbooks, and proof/closure material remain importa
 
 ## Guiding Principle
 
-This repo is not trying to become a generic office clone.
-
-It is building fidelity-first office-document runtimes with explicit preservation and calm, reviewable UI.
+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
 
@@ -663,7 +753,7 @@ Fired when the document transitions between clean and dirty (unsaved) states.
 
 #### `story_changed`
 
-Fired when the user navigates between document stories (e.g. main body → header/footer).
+Fired when the user navigates between document stories (e.g. main body -> header/footer).
 
 ```ts
 {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/package-version.ts

@@ -0,0 +1,13 @@
+/**
+ * Package version string — pinned to package.json `version`.
+ *
+ * Consumed by export paths that embed a producer identity (e.g.
+ * `/docProps/app.xml` `<Application>` tag) so exported packages can be
+ * traced back to the exact runtime release.
+ *
+ * Keep this in lockstep with `package.json#version`. A future enhancement
+ * would be to generate this file from package.json at build time; for now
+ * the string is committed directly so the runtime works without a build
+ * step for tests.
+ */
+export const PACKAGE_VERSION = "1.0.36";

package/src/api/public-types.ts

@@ -1,4 +1,60 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
+import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
+
+export type {
+  WordReviewEditorLayoutFacet,
+  LayoutFacetEvent,
+  LayoutFacetInvalidationReason,
+  PublicBlockFragment,
+  PublicBlockMeasurement,
+  PublicFieldDirtinessReport,
+  PublicLineBox,
+  PublicMeasurementFidelity,
+  PublicNoteAllocation,
+  PublicPageAnchor,
+  PublicPageNode,
+  PublicPageRegion,
+  PublicPageRegions,
+  PublicPageSpan,
+  PublicResolvedPageStories,
+  PublicResolvedParagraphFormatting,
+  PublicResolvedRunFormatting,
+  PublicSectionNode,
+  // R0.5: named page-format + margin-preset catalogs
+  PageFormatDefinition,
+  ActivePageFormat,
+  MarginPresetDefinition,
+  ActiveMarginPreset,
+  RenderZoomSummary,
+} from "../runtime/layout/public-facet.ts";
+
+// R1: render-kernel shapes (frame, decoration index, anchor index) — these
+// are exposed additively so consumers can read the future `getRenderFrame`
+// output without depending on the internal render kernel module.
+export type {
+  RenderFrame,
+  RenderPage,
+  RenderPageRegions,
+  RenderStoryRegion,
+  RenderBlock,
+  RenderLine,
+  RenderLineAnchor,
+  RenderBlockDecoration,
+  RenderFrameRect,
+  RenderZoom,
+  RenderAnchorIndex,
+  RenderAnchorQuery,
+  RenderFrameQueryOptions,
+  RenderHitResult,
+  RenderKernelEvent,
+  RenderPoint,
+  DecorationIndex,
+  PageChromeReservations,
+} from "../runtime/render/index.ts";
+
+// R0: scope-rail posture vocabulary and chrome pin state — exposed so
+// host apps can drive the editor role and render custom posture menus.
+export type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
 
 export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
 export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
@@ -767,6 +823,7 @@ export type SurfaceBlockSnapshot =
       keepNext?: boolean;
       keepLines?: boolean;
       pageBreakBefore?: boolean;
+      widowControl?: boolean;
       outlineLevel?: number;
       bidi?: boolean;
       suppressLineNumbers?: boolean;
@@ -1013,9 +1070,231 @@ export interface TableStructureContextSnapshot {
     mergeCells: TableOperationCapabilitySnapshot;
     splitCell: TableOperationCapabilitySnapshot;
     deleteTable: TableOperationCapabilitySnapshot;
+    // P2g — table-level authoring ops
+    setTableWidth: TableOperationCapabilitySnapshot;
+    setTableAlignment: TableOperationCapabilitySnapshot;
+    setTableIndent: TableOperationCapabilitySnapshot;
+    setTableLayoutMode: TableOperationCapabilitySnapshot;
+    setTableCellMargins: TableOperationCapabilitySnapshot;
+    setTableBorders: TableOperationCapabilitySnapshot;
+    setTableCaption: TableOperationCapabilitySnapshot;
+    setTableDescription: TableOperationCapabilitySnapshot;
+    // P2h — column / row sizing + row props
+    setColumnWidth: TableOperationCapabilitySnapshot;
+    distributeColumnsEvenly: TableOperationCapabilitySnapshot;
+    setRowHeight: TableOperationCapabilitySnapshot;
+    setRowCantSplit: TableOperationCapabilitySnapshot;
+    setRowIsHeader: TableOperationCapabilitySnapshot;
+    setRowAlignment: TableOperationCapabilitySnapshot;
+    insertRows: TableOperationCapabilitySnapshot;
+    insertColumns: TableOperationCapabilitySnapshot;
+    // P2i — cell-level ops (over a locator)
+    setCellBorders: TableOperationCapabilitySnapshot;
+    setCellShading: TableOperationCapabilitySnapshot;
+    clearCellShading: TableOperationCapabilitySnapshot;
+    setCellMargins: TableOperationCapabilitySnapshot;
+    setCellVerticalAlign: TableOperationCapabilitySnapshot;
+    setCellTextDirection: TableOperationCapabilitySnapshot;
+    setCellNoWrap: TableOperationCapabilitySnapshot;
+    setCellFitText: TableOperationCapabilitySnapshot;
   };
 }
 
+// ─── Table typed-op surface (P2.5) ───────────────────────────────────────────
+
+/**
+ * Width/height unit used by OOXML table properties.
+ */
+export interface PublicTableWidth {
+  value: number;
+  type: "dxa" | "auto" | "pct" | "nil";
+}
+
+/**
+ * Reusable border-spec shape for table-level and cell-level borders.
+ * Matches OOXML w:*Borders child attributes.
+ */
+export interface PublicBorderSpec {
+  value?: string;
+  size?: number;
+  space?: number;
+  color?: string;
+}
+
+export interface PublicTableBorders {
+  top?: PublicBorderSpec;
+  left?: PublicBorderSpec;
+  bottom?: PublicBorderSpec;
+  right?: PublicBorderSpec;
+  insideH?: PublicBorderSpec;
+  insideV?: PublicBorderSpec;
+}
+
+export interface PublicTableCellBorders {
+  top?: PublicBorderSpec;
+  left?: PublicBorderSpec;
+  bottom?: PublicBorderSpec;
+  right?: PublicBorderSpec;
+  insideH?: PublicBorderSpec;
+  insideV?: PublicBorderSpec;
+}
+
+export interface PublicTableCellMargins {
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+}
+
+export interface PublicCellShading {
+  fill?: string;
+  color?: string;
+  val?: string;
+}
+
+/**
+ * Addresses a cell (or set of cells) for locator-driven cell-level ops.
+ *
+ *  - `anchor`: the currently anchored cell from the active selection
+ *  - `index`: explicit (rowIndex, columnIndex)
+ *  - `rect`:  rectangular range in logical grid coordinates
+ *  - `row` / `column`: all cells in a single row or column
+ *  - `selection`: whatever the active selection covers
+ */
+export type PublicCellLocator =
+  | { kind: "anchor" }
+  | { kind: "index"; rowIndex: number; columnIndex: number }
+  | {
+      kind: "rect";
+      rect: { top: number; left: number; bottom: number; right: number };
+    }
+  | { kind: "row"; rowIndex: number }
+  | { kind: "column"; columnIndex: number }
+  | { kind: "selection" };
+
+/**
+ * Discriminated union of every table operation the public API exposes.
+ * Mirrors the internal `TableStructureOperation` variants on a stable
+ * kebab-case `kind` discriminator.
+ *
+ * Stability: additive. New ops land as new `kind` values; existing
+ * variants keep the same shape across minor versions.
+ */
+export type TableOp =
+  | { kind: "insert"; rows: number; columns: number }
+  | { kind: "delete-table" }
+  | { kind: "add-row-before" }
+  | { kind: "add-row-after" }
+  | { kind: "add-column-before" }
+  | { kind: "add-column-after" }
+  | { kind: "delete-row" }
+  | { kind: "delete-column" }
+  | { kind: "merge-cells" }
+  | { kind: "split-cell" }
+  | { kind: "set-cell-background"; color: string }
+  // Table-level (P2g)
+  | { kind: "set-table-width"; width: PublicTableWidth }
+  | { kind: "set-table-alignment"; alignment: "left" | "center" | "right" }
+  | { kind: "set-table-indent"; indent: PublicTableWidth }
+  | { kind: "set-table-layout-mode"; mode: "fixed" | "autofit" }
+  | { kind: "set-table-cell-margins"; margins: Partial<PublicTableCellMargins> }
+  | { kind: "set-table-borders"; borders: Partial<PublicTableBorders> }
+  | { kind: "set-table-style"; styleId: string | null }
+  | { kind: "set-table-caption"; caption: string | null }
+  | { kind: "set-table-description"; description: string | null }
+  // Column / row sizing + row props (P2h)
+  | { kind: "set-column-width"; columnIndex: number; twips: number }
+  | {
+      kind: "distribute-columns-evenly";
+      columnRange?: { from: number; to: number };
+    }
+  | {
+      kind: "set-row-height";
+      rowIndex: number;
+      twips: number;
+      rule: "auto" | "atLeast" | "exact";
+    }
+  | { kind: "set-row-cant-split"; rowIndex: number; value: boolean }
+  | { kind: "set-row-is-header"; rowIndex: number; value: boolean }
+  | {
+      kind: "set-row-alignment";
+      rowIndex: number;
+      alignment: "left" | "center" | "right";
+    }
+  | {
+      kind: "insert-rows";
+      rowIndex: number;
+      at: "before" | "after";
+      count: number;
+    }
+  | {
+      kind: "insert-columns";
+      columnIndex: number;
+      at: "before" | "after";
+      count: number;
+      widths?: readonly number[];
+    }
+  // Cell-level (P2i)
+  | {
+      kind: "set-cell-borders";
+      locator: PublicCellLocator;
+      borders: Partial<PublicTableCellBorders>;
+    }
+  | {
+      kind: "set-cell-shading";
+      locator: PublicCellLocator;
+      shading: Partial<PublicCellShading> | null;
+    }
+  | { kind: "clear-cell-shading"; locator: PublicCellLocator }
+  | {
+      kind: "set-cell-margins";
+      locator: PublicCellLocator;
+      margins: Partial<PublicTableCellMargins>;
+    }
+  | {
+      kind: "set-cell-vertical-align";
+      locator: PublicCellLocator;
+      align: "top" | "center" | "bottom";
+    }
+  | {
+      kind: "set-cell-text-direction";
+      locator: PublicCellLocator;
+      direction: "lrTb" | "tbRl" | "btLr";
+    }
+  | { kind: "set-cell-no-wrap"; locator: PublicCellLocator; value: boolean }
+  | { kind: "set-cell-fit-text"; locator: PublicCellLocator; value: boolean };
+
+/**
+ * Outcome of `ref.tables.apply(op)`.
+ */
+export interface TableOpResult {
+  /** Whether the op mutated canonical document state. */
+  changed: boolean;
+  /**
+   * When the op was refused (e.g. no table selection, merge not clean),
+   * a short human-readable reason. `null` when the op committed.
+   */
+  coercedReason: string | null;
+  /**
+   * Fresh capability snapshot post-op. `null` when there is no table in
+   * the current selection.
+   */
+  capabilities: TableStructureContextSnapshot | null;
+}
+
+/**
+ * The `tables` property on `WordReviewEditorRef`. Minimal surface in this
+ * phase: a typed dispatch boundary for every table op plus a capability
+ * read. Read-only geometry queries (columns, rows, render plan, ...)
+ * land with the layout engine + render kernel integration.
+ */
+export interface WordReviewEditorTablesFacet {
+  /** Dispatch a typed table op through the runtime. */
+  apply(op: TableOp): TableOpResult;
+  /** Current capability snapshot for the active table selection. */
+  getCapabilities(): TableStructureContextSnapshot | null;
+}
+
 export interface PageRegionHitTest {
   region: "body" | "header" | "footer" | "margin" | "gutter";
   sectionIndex: number;
@@ -1044,8 +1323,50 @@ export interface EditorViewStateSnapshot {
   activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
   measurement: LayoutMeasurement;
   isFocused: boolean;
+  /**
+   * Role-scoped chrome dimension (spec §6.4).  Drives which action set the
+   * top toolbar renders: `"editor"` exposes authoring (insert, format,
+   * Mark-section menu, tracked-changes toggle), `"review"` exposes review
+   * queue nav + accept/reject, `"workflow"` exposes work-item traversal.
+   * Independent of `viewMode` / `documentMode`.
+   */
+  editorRole: EditorRole;
+  /**
+   * Pin state for detachable chrome surfaces — topnav and the selection
+   * tier tool.  Absent key means "docked default"; `detached: true` means
+   * the surface renders as a floating, user-positioned panel.  State is
+   * runtime-owned, per-session, and survives snapshot rebuilds.
+   */
+  chromePins: ChromePinsState;
+}
+
+/**
+ * Role-scoped chrome dimension (spec §6.4 of runtime-rendering-and-chrome-phase.md).
+ *
+ * - `"editor"` — authoring posture.  Toolbar surfaces format, insert menu,
+ *   Mark-section posture menu, tracked-changes display toggle, comment.
+ * - `"review"` — reviewing posture.  Toolbar surfaces prev/next, accept,
+ *   reject, accept-all / reject-all in scope, markup mode, comment.
+ * - `"workflow"` — workflow-actor posture.  Toolbar surfaces prev/next
+ *   work item, claim, skip, mark complete, mark blocked, jump to scope.
+ */
+export type EditorRole = "editor" | "review" | "workflow";
+
+/**
+ * Chrome surfaces that can be detached into a floating, draggable panel.
+ * Extend this union as new surfaces adopt the `DraggableFloat` primitive.
+ */
+export type ChromePinSurface = "topnav" | "selectionTier";
+
+export interface PinState {
+  /** True when the surface is detached from its default dock. */
+  detached: boolean;
+  /** User-chosen offset in CSS px from the surface's dock origin. */
+  offset: { x: number; y: number };
 }
 
+export type ChromePinsState = Partial<Record<ChromePinSurface, PinState>>;
+
 export interface CommandStateSnapshot {
   canUndo: boolean;
   canRedo: boolean;
@@ -1916,13 +2237,46 @@ export interface WordReviewEditorRef {
   getRuntimeContextAnalytics(
     query?: RuntimeContextAnalyticsQuery,
   ): RuntimeContextAnalyticsSnapshot | null;
+
+  /**
+   * Runtime-owned layout facet.
+   *
+   * The ergonomic surface for walking the page graph, resolving offsets to
+   * fragments, inspecting formatting, and observing layout events.  Prefer
+   * this over `getPageLayoutSnapshot()` / `getDocumentNavigationSnapshot()`
+   * for new code — those remain as thin adapters for compatibility.
+   *
+   * Returns `null` only when the runtime is still loading; once the `ready`
+   * event has fired, the facet is always available.
+   */
+  readonly layout: WordReviewEditorLayoutFacet;
+  /**
+   * Typed dispatch boundary for every table operation the runtime
+   * supports. Existing flat verbs (`addRowBefore`, `setCellBackground`,
+   * …) remain as compatibility wrappers; new ops land through
+   * `ref.tables.apply(op)` with a typed discriminated union.
+   */
+  readonly tables: WordReviewEditorTablesFacet;
 }
 
+/**
+ * Density + role-scoped chrome preset.
+ *
+ * Historically a pure density knob (`selection` → `simple` → `advanced` →
+ * `review` progressively exposed more chrome).  `"workflow"` was added in
+ * chrome-phase R1 to surface workflow-actor primary actions (prev/next
+ * work item, claim, skip, mark complete, jump to scope) inline in the
+ * top toolbar.  Host apps that already use `chromePreset` keep working
+ * unchanged; consumers that want the new workflow view set the preset
+ * to `"workflow"`.  For finer-grained role control independent of
+ * density, set `editorRole` on the view state directly.
+ */
 export type WordReviewEditorChromePreset =
   | "selection"
   | "simple"
   | "advanced"
-  | "review";
+  | "review"
+  | "workflow";
 
 export interface WordReviewEditorChromeOptions {
   showReviewQueueBar: boolean;
@@ -1970,3 +2324,50 @@ export interface WordReviewEditorChromeVisibility {
   statusBar: boolean;
   reviewRail: boolean;
 }
+
+// ---------------------------------------------------------------------------
+// Bounded local-first predicted-text lane contract
+// ---------------------------------------------------------------------------
+
+export type TextCommandAckKind =
+  | "equivalent"
+  | "adjusted"
+  | "rejected"
+  | "structural-divergence";
+
+export interface ScopeTagTouch {
+  /** Tag family: "comment" | "revision" | "field" | "bookmark" | "sdt" | "opaque" | custom string. */
+  tagType: string;
+  tagId: string;
+  behavior: "extended" | "trimmed" | "split" | "detached" | "unchanged";
+  range: { from: number; to: number };
+}
+
+/**
+ * Sync reconciliation result returned by `DocumentRuntime.applyActiveStoryTextCommand`.
+ *
+ * The predicted-text lane in the mounted editor dispatches a local PM transaction,
+ * then calls the runtime synchronously. The ack tells the lane how to reconcile:
+ *
+ * - `equivalent`: runtime accepted the edit and produced the same text shape;
+ *   the lane can skip the Lane A PM rebuild entirely.
+ * - `adjusted`: runtime accepted but normalized or added review marks; the lane
+ *   patches the affected range from the canonical snapshot.
+ * - `rejected`: runtime blocked the edit (workflow, protection, read-only);
+ *   the lane rolls back the predicted PM range from its pre-image.
+ * - `structural-divergence`: the command affected structure beyond the
+ *   predicted range; the lane falls back to a full PM rebuild.
+ */
+export interface TextCommandAck {
+  kind: TextCommandAckKind;
+  /** Opaque id echoed back from the predicted op. Undefined for canonical callers. */
+  opId?: string;
+  /** Revision token of the document AFTER commit. Empty string when `kind === "rejected"`. */
+  newRevisionToken: string;
+  /** For `adjusted`: the canonical range that differs from the prediction. */
+  adjustedRange?: { fromRuntime: number; toRuntime: number };
+  /** For `rejected`: the blocked reasons. */
+  blockedReasons?: readonly { code: string; message: string }[];
+  /** Tag touches the runtime applied so the lane can redraw decorations without a PM rebuild. */
+  scopeTagTouches?: readonly ScopeTagTouch[];
+}

package/src/core/commands/index.ts

@@ -35,6 +35,7 @@ import {
 } from "./text-commands.ts";
 import type { RevisionRecord as CanonicalRevisionRecord } from "../../model/canonical-document.ts";
 import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
+import { collectScopeTagTouches } from "../../review/store/scope-tag-diff.ts";
 import { applyRevisionRuntimeCommand } from "../../runtime/revision-runtime.ts";
 import type { RevisionStore } from "../../review/store/revision-store.ts";
 
@@ -878,6 +879,22 @@ function applyTextCommand(
     result.mapping,
   );
 
+  const scopeTagTouches = collectScopeTagTouches(
+    state.document.review.comments,
+    reviewState.document.review.comments,
+    state.document.review.revisions,
+    reviewState.document.review.revisions,
+  );
+  const mappingWithTouches: TransactionMapping = scopeTagTouches.length > 0
+    ? {
+        ...result.mapping,
+        metadata: {
+          ...(result.mapping.metadata ?? {}),
+          scopeTagTouches,
+        },
+      }
+    : result.mapping;
+
   return createTransaction(
     {
       ...state,
@@ -892,7 +909,7 @@ function applyTextCommand(
     {
       historyBoundary: "push",
       markDirty: true,
-      mapping: result.mapping,
+      mapping: mappingWithTouches,
       effects: reviewState.effects,
     },
   );