@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/api/public-types.ts

@@ -1,3 +1,4 @@
+import type { ReactNode } from "react";
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
 import type { HarnessDebugPorts } from "../internal/harness-debug-ports.ts";
 import type { BlockNode, CanonicalParagraphFormatting, CanonicalRunFormatting, TextMark } from "../model/canonical-document.ts";
@@ -482,6 +483,45 @@ export interface SearchOptions {
   matchCase?: boolean;
   wholeWord?: boolean;
   limit?: number;
+  /** Phase C §C3 — treat `query` as a JS regex pattern (compiled with `u` flag). */
+  regex?: boolean;
+  /** Phase C §C3 — restrict results to positions inside this scopeId's marker range. */
+  inScope?: string;
+  /** Phase C §C3 — restrict results to a specific story target (default: main). */
+  inStory?: EditorStoryTarget;
+}
+
+/**
+ * §C4 — Post-match formatting filter for `findTextWithStyle`.
+ */
+export interface TextStyleFilter {
+  /** Match only inside heading paragraphs (outlineLevel set or styleId matches /^Heading\d/i). */
+  inHeading?: boolean;
+  /** Run-level marks that ALL segments in the match must carry (AND per property, AND across segments). */
+  hasFormatting?: {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+  };
+  /** Run-level marks where ALL segments must have AT LEAST ONE (OR per property, AND across segments). */
+  anyFormatting?: {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+  };
+}
+
+/** Phase C §C5 — options for programmatic selection changes. */
+export interface SetSelectionOptions {
+  /**
+   * When `true`, the selection change is applied locally but suppresses
+   * the next awareness cursor publish. Useful for agent-driven
+   * programmatic navigation that should not broadcast a cursor flicker
+   * to collaborators.
+   */
+  silent?: boolean;
 }
 
 export interface SearchResultSnapshot {
@@ -826,6 +866,8 @@ export interface SurfaceDrawingAnchor {
   simplePos?: boolean;
   /** docPr.id / .name / .descr — used for accessibility chrome and selection labels. */
   docPr?: { id: string; name?: string; descr?: string };
+  /** Polygon coords (21600ths-of-image units) for tight/through wrap clipping. Lane 6d N9.b. */
+  wrapPolygon?: Array<{ x: number; y: number }>;
 }
 
 /**
@@ -841,6 +883,12 @@ export interface SurfacePictureEffects {
   flipV?: boolean;
   presetGeom?: string;
   stretch?: boolean;
+  /** N11.b — a:softEdge feather radius in EMU. Maps to CSS `filter: blur(R)`. */
+  softEdgeRadius?: number;
+  /** N11.b — a:outerShdw drop shadow. `blurRad`/`dist` in EMU; `dir` in 60000ths of a degree. */
+  outerShadow?: { blurRad: number; dist: number; dir: number; color: string; colorType: "srgbClr" | "schemeClr" };
+  /** N11.b — a:glow ambient glow. `radius` in EMU. */
+  glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
 }
 
 export type SurfaceInlineSegment =
@@ -1043,6 +1091,8 @@ export interface ResolvedNumberingSnapshot {
   geometry: ResolvedNumberingGeometrySnapshot;
   /** CASCADED marker run formatting: docDefaults → paragraph style chain rPr → paragraph-mark rPr → level rPr. Added in Task 11. The raw level rPr is still available at geometry.markerRunProperties. */
   markerRunProperties?: CanonicalRunFormatting;
+  /** Media-catalog ID for picture-bullet images (CO3.9). Set when the numbering level has `picBulletId` that resolves to a NumPicBullet entry. */
+  picBulletMediaId?: string;
 }
 
 export type SurfaceBlockSnapshot =
@@ -1065,7 +1115,14 @@ export type SurfaceBlockSnapshot =
       spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
       contextualSpacing?: boolean;
       indentation?: { left?: number; right?: number; firstLine?: number; hanging?: number };
-      borders?: { top?: unknown; left?: unknown; bottom?: unknown; right?: unknown; bar?: unknown; between?: unknown };
+      borders?: {
+        top?: PublicBorderSpec | null;
+        left?: PublicBorderSpec | null;
+        bottom?: PublicBorderSpec | null;
+        right?: PublicBorderSpec | null;
+        bar?: PublicBorderSpec | null;
+        between?: PublicBorderSpec | null;
+      };
       shading?: { fill?: string; color?: string; val?: string };
       tabStops?: Array<{ pos: number; val?: string; leader?: string }>;
       keepNext?: boolean;
@@ -1084,6 +1141,14 @@ export type SurfaceBlockSnapshot =
       to: number;
       styleId?: string;
       gridColumns: number[];
+      /**
+       * SOW gap G1 — when `tableResolved.widthType === "pct"`, a parallel array
+       * of relative column widths (percent 0–100) derived from `gridColumns`
+       * twips. The node-view prefers these for the `<colgroup>` so the column
+       * proportions track the table's percent width instead of the absolute
+       * `pt` values drifting against a `width: 100%` container.
+       */
+      gridColumnsRelative?: number[] | null;
       alignment?: "left" | "center" | "right";
       tblLook?: {
         /** R2d: raw `w:tblLook/@w:val` hex so vendor-extended bits survive round-trip. */
@@ -1194,7 +1259,8 @@ export type EditorWarningCode =
   | "revision_anchor_detached"
   | "large_document_degraded"
   | "font_substitution"
-  | "image_missing";
+  | "image_missing"
+  | "review_target_not_found";
 
 export interface EditorWarning {
   warningId: string;
@@ -1211,6 +1277,13 @@ export interface EditorWarning {
   affectedAnchor?: EditorAnchorProjection;
   featureEntryId?: string;
   details?: Record<string, unknown>;
+  /**
+   * v2.0.0 — dual-error composite carrying a machine-facing `technical`
+   * payload and an LLM-facing `llmMetadata` payload. Populated by the
+   * editor on every warning emitted from v2.0.0 onward; older snapshots
+   * may omit it. See {@link EditorDiagnostic}.
+   */
+  diagnostic?: EditorDiagnostic;
 }
 
 export type EditorErrorCode =
@@ -1228,6 +1301,149 @@ export interface EditorError {
   isFatal: boolean;
   source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
   details?: Record<string, unknown>;
+  /**
+   * v2.0.0 — dual-error composite. See {@link EditorDiagnostic}. Populated
+   * by the editor from v2.0.0 onward; older snapshots may omit it.
+   */
+  diagnostic?: EditorDiagnostic;
+}
+
+// ---------------------------------------------------------------------------
+// v2.0.0 — dual-error diagnostic composite
+// ---------------------------------------------------------------------------
+
+/**
+ * Unified source origin for any diagnostic emitted by the editor.
+ * Superset of {@link EditorWarning.source} and {@link EditorError.source}
+ * to cover API-surface + host-adapter rejections uniformly.
+ */
+export type EditorDiagnosticSource =
+  | "import"
+  | "export"
+  | "runtime"
+  | "review"
+  | "preservation"
+  | "validation"
+  | "datastore"
+  | "host"
+  | "api";
+
+/**
+ * Canonical machine-scannable code for every diagnostic surface in the
+ * public API. Prefixed by convention (`import.*`, `export.*`, `runtime.*`,
+ * `host.*`, `api.*`, `review.*`, `preservation.*`, `validation.*`).
+ *
+ * Legacy codes from {@link EditorWarningCode} / {@link EditorErrorCode} are
+ * bridged into this union via the metadata table in
+ * `src/runtime/diagnostics/code-metadata-table.ts`.
+ *
+ * Stability: `advanced-supported`. New codes are additive; existing codes
+ * are permanent. Removal requires a major version bump.
+ */
+export type EditorDiagnosticCode =
+  | "import.failed"
+  | "import.package_corrupt"
+  | "import.normalized"
+  | "import.unsupported_ooxml_preserved"
+  | "import.unsupported_ooxml_locked"
+  | "export.failed"
+  | "export.roundtrip_risk"
+  | "review.comment_anchor_detached"
+  | "review.revision_anchor_detached"
+  | "runtime.large_document_degraded"
+  | "runtime.font_substitution"
+  | "runtime.image_missing"
+  | "runtime.internal_invariant"
+  | "host.adapter_rejected"
+  | "host.load_rejected"
+  | "host.save_rejected"
+  | "host.chart_preview_rejected"
+  | "datastore.failed"
+  | "datastore.load_rejected"
+  | "datastore.save_rejected"
+  | "validation.failed"
+  | "validation.invariant_violated"
+  | "api.invalid_regex"
+  | "api.invalid_anchor"
+  | "api.invalid_argument"
+  | "api.metadata_resolver_missing"
+  | "api.metadata_resolver_rejected"
+  | "api.scope_not_found"
+  | "api.collab_role_restricted"
+  | "api.workflow_comment_only"
+  | "api.command_blocked"
+  // Lane 8 Track H (v2.x) — agent-helper widening. Metadata registered in
+  // Phase 1; emission sites land with the Phase 2 runtime wiring.
+  | "api.projection_unavailable"
+  | "api.batch_edit_collision"
+  | "api.workflow_patch_invalid"
+  | "api.change_id_unknown"
+  | "api.ai_explanation_anchor_invalid";
+
+/**
+ * The recovery class an agent / LLM uses to decide whether to retry,
+ * reprompt, fall back, or surface to a human. Stable + enumerated.
+ */
+export type EditorDiagnosticRecoveryClass =
+  | "retry-safe"
+  | "retry-with-backoff"
+  | "requires-input"
+  | "requires-resolver"
+  | "requires-permission"
+  | "requires-human"
+  | "unrecoverable";
+
+/**
+ * Structured remediation the LLM can act on.
+ */
+export type EditorDiagnosticRemediation =
+  | { kind: "none" }
+  | { kind: "retry"; afterMs?: number; maxAttempts?: number }
+  | { kind: "fallback"; suggestion: string; payload?: Record<string, unknown> }
+  | {
+      kind: "escalate";
+      to: "host" | "author" | "reviewer" | "admin";
+      reason: string;
+    };
+
+/** Developer / machine-facing payload. */
+export interface EditorDiagnosticTechnical {
+  message: string;
+  source: EditorDiagnosticSource;
+  stack?: string;
+  cause?: {
+    message: string;
+    name?: string;
+    stack?: string;
+  };
+  details?: Record<string, unknown>;
+  affectedAnchor?: EditorAnchorProjection;
+  featureEntryId?: string;
+}
+
+/** LLM / agent-facing payload. */
+export interface EditorDiagnosticLlmMetadata {
+  userSummary: string;
+  remediation: EditorDiagnosticRemediation;
+  recoveryClass: EditorDiagnosticRecoveryClass;
+  echoedInput?: Record<string, unknown>;
+  docsUrl?: string;
+  tags?: string[];
+}
+
+/**
+ * v2.0.0 dual-error composite. LLM consumers read `llmMetadata` only;
+ * developer consumers read `technical`. Host UI renders
+ * `llmMetadata.userSummary` to end users. See
+ * `docs/wiki/error-catalog.md` for the full code catalog.
+ */
+export interface EditorDiagnostic {
+  diagnosticId: string;
+  severity: "fatal" | "error" | "warning" | "info";
+  code: EditorDiagnosticCode;
+  technical: EditorDiagnosticTechnical;
+  llmMetadata: EditorDiagnosticLlmMetadata;
+  emittedAt: string;
 }
 
 export type CompatibilityFeatureClass =
@@ -1812,6 +2028,8 @@ export interface RuntimeRenderSnapshot {
   commandState: CommandStateSnapshot;
   surface?: EditorSurfaceSnapshot;
   protectionSnapshot: ProtectionSnapshot;
+  /** R.3 — stable id of the currently grabbed image/shape, or null. Populated from grab state so chrome overlays re-render on selectObject/deselectObject. */
+  grabbedObjectId?: string | null;
 }
 
 export interface EditorSessionState {
@@ -1910,6 +2128,27 @@ export interface AddScopeResult {
 export interface ExportDocxOptions {
   fileName?: string;
   reason?: string;
+  /**
+   * @experimental Lane 7c Slice 7c.4 (v2.0.0) — opt-in for Strict-flavor
+   * OOXML export (ECMA-376 / ISO 29500-1 Strict, namespaces under
+   * `http://purl.oclc.org/ooxml/...`). Transitional remains the default.
+   *
+   * **Status:** wired — `true` switches `serializeMainDocument` to the
+   * Strict namespace URI set (`w`, `r`, `a`, `pic`, `wp`, `mc`) and
+   * omits Microsoft extension namespace declarations
+   * (`w14`/`w15`/`w16*`/`wp14`/`wps`) from the root element. `false`
+   * or omitted preserves Transitional output byte-equivalent to
+   * pre-7c.4 behavior.
+   *
+   * **Known scope limitations:** relationship `Type` URIs and
+   * Content-Type URIs still use the Transitional form; extension
+   * content wrapping via `mc:AlternateContent` / `mc:Fallback` is
+   * not yet emitted. Full ISO 29500 Strict compliance requires those
+   * follow-ups before this option graduates from `@experimental`.
+   * See `docs/wiki/compatibility-and-validation.md` § Strict-flavor
+   * export for the current capability matrix.
+   */
+  exportStrictOoxml?: boolean;
 }
 
 export interface ExportDelivery {
@@ -1926,6 +2165,35 @@ export interface ExportResult {
 
 export type WorkflowScopeMode = "edit" | "suggest" | "comment" | "view";
 
+/**
+ * §C7 — Local chrome visibility mode. Never collab-replicated.
+ * - `"all"`:      show all scope rail entries + decorations (default).
+ * - `"none"`:     suppress all scope chrome; data layer unaffected.
+ * - `"filtered"`: show only scopes matching `filter`.
+ */
+export type ScopeChromeVisibility = "all" | "none" | "filtered";
+
+/**
+ * §C7 — Full chrome visibility state including an optional filter (only
+ * relevant when `mode === "filtered"`).
+ */
+export interface ScopeChromeVisibilityState {
+  mode: ScopeChromeVisibility;
+  filter?: ScopeQueryFilter;
+}
+
+/**
+ * §C8 — Per-scope chrome visibility. Default when absent is `"visible"`.
+ * Collab-replicated: all peers see the same value. Distinct from
+ * `setScopeChromeVisibility` (§C7), which is local view-state.
+ *
+ * - `"visible"`:   rail entry + card + inline decoration (current behavior).
+ * - `"hidden"`:    in the rail but muted; card opens on explicit click; no decoration.
+ * - `"invisible"`: never rendered; only queryable via API. Does NOT contribute
+ *   to InteractionGuard unless `mode === "view"` (explicit host opt-in).
+ */
+export type ScopeVisibility = "visible" | "hidden" | "invisible";
+
 export interface WorkflowCandidateRange {
   candidateId: string;
   storyTarget?: EditorStoryTarget;
@@ -1951,6 +2219,12 @@ export interface WorkflowScope {
    * `"inherit"`.
    */
   metadataPersistence?: ScopeMetadataPersistence;
+  /**
+   * §C8 — Per-scope chrome visibility. Absent / `undefined` is equivalent to
+   * `"visible"`. Collab-replicated via the existing `workflow.set-overlay`
+   * broadcast; old peers ignore the unknown field (read as `undefined` = visible).
+   */
+  visibility?: ScopeVisibility;
 }
 
 export interface WorkflowScopeMetadataField {
@@ -2042,6 +2316,67 @@ export interface WorkflowMetadataSnapshot {
   entries: WorkflowMetadataEntry[];
 }
 
+// ---------------------------------------------------------------------------
+// Phase C — host-side scope query surface (§C1, §C2)
+// ---------------------------------------------------------------------------
+
+/**
+ * §C1 — Filter passed to `queryScopes` / `findScopesAt` /
+ * `findScopesIntersecting`. All fields are optional and AND'd together.
+ * Snapshot-based; never triggers runtime mutation.
+ */
+export interface ScopeQueryFilter {
+  /** Match only scopes attached to any of these work items. */
+  workItemIds?: string[];
+  /** Match only scopes in one of these modes. */
+  modes?: WorkflowScopeMode[];
+  /** Match only scopes whose `domain` is one of these. */
+  domains?: Array<NonNullable<WorkflowScope["domain"]>>;
+  /**
+   * Match scopes that carry at least one entry with this `metadataId`.
+   * Uses the runtime `WorkflowMetadataSnapshot` joined by `entry.scopeId`.
+   */
+  metadataId?: string;
+  /**
+   * Match scopes that carry at least one entry whose `value` passes the
+   * predicate. Entries with no `value` are skipped.
+   */
+  hasValue?: (value: Record<string, unknown>, entry: WorkflowMetadataEntry) => boolean;
+  /** Label prefix (case-insensitive). */
+  labelPrefix?: string;
+  /**
+   * Story target filter. Defaults to `{ kind: "main" }` when omitted. Pass
+   * `"*"` for any story.
+   */
+  storyTarget?: EditorStoryTarget | "*";
+  /** Max result count. Undefined = no cap. */
+  limit?: number;
+  /**
+   * §C8 — include scopes with `visibility: "hidden"`. Default: false.
+   * Accepted but has no effect until §C8 adds the `visibility` field.
+   */
+  includeHidden?: boolean;
+  /**
+   * §C8 — include scopes with `visibility: "invisible"`. Default: false.
+   * Accepted but has no effect until §C8 adds the `visibility` field.
+   */
+  includeInvisible?: boolean;
+}
+
+/**
+ * §C1 — One result from `queryScopes`. Joins the scope record with the
+ * metadata entries that point at it and the resolved work item (when
+ * `scope.workItemId` matches one in the overlay).
+ */
+export interface ScopeQueryResult {
+  /** Scope record from the overlay. */
+  scope: WorkflowScope;
+  /** Metadata entries whose `entry.scopeId === scope.scopeId`. */
+  entries: WorkflowMetadataEntry[];
+  /** Resolved work item when `scope.workItemId` is set and present. */
+  workItem: WorkflowWorkItem | null;
+}
+
 // ---------------------------------------------------------------------------
 // R2 — issue metadata (scope-card-overlay P1)
 // ---------------------------------------------------------------------------
@@ -2164,6 +2499,8 @@ export interface ScopeCardModel {
   posture: ScopeRailPosture;
   label: string;
   primaryAnchorRect: RenderFrameRect | null;
+  /** K2 — source anchor for the scope; passed to `onScopeAskAgent` so hosts skip a `getScope()` round-trip. */
+  anchor?: EditorAnchorProjection;
   issue?: IssueMetadataValue;
   /** Id-only lookup; `suggestionGroups` holds the full entries. */
   suggestionGroupIds: readonly string[];
@@ -2228,6 +2565,13 @@ export interface InteractionGuardSnapshot {
   effectiveMode: EffectiveSelectionMode;
   matchedScopeId?: string;
   matchedScopeMode?: WorkflowScopeMode;
+  /** §C6 — all scopes covering the selection, ordered outermost→innermost
+   * (widest span first). Most-restrictive mode wins for effectiveMode. */
+  matchedScopeStack?: Array<{
+    scopeId: string;
+    mode: WorkflowScopeMode;
+    visibility: ScopeVisibility;
+  }>;
   targetAccess?: "direct-edit" | "suggest" | "comment-only" | "view-only" | "blocked";
   commandCapabilities?: Array<{
     family: "text" | "formatting" | "structure";
@@ -2571,8 +2915,25 @@ export type AutosaveState =
   | { status: "saved"; savedAt: string }
   | { status: "error"; error: EditorError };
 
+/**
+ * Controls the editor's automatic session-state persistence behaviour.
+ * Passed as `autosave` on `WordReviewEditorProps`.
+ *
+ * When omitted entirely, autosave is **enabled** with a 2 000 ms debounce.
+ */
 export interface AutosaveConfig {
+  /**
+   * Set to `false` to disable autosave entirely.
+   * @default true
+   */
   enabled?: boolean;
+  /**
+   * Milliseconds of idle time after the last edit before
+   * `hostAdapter.saveSession` is called. Minimum effective value is
+   * 500 ms (values below are clamped). Has no effect when `enabled` is
+   * `false`.
+   * @default 2000
+   */
   debounceMs?: number;
 }
 
@@ -2635,8 +2996,8 @@ export type WordReviewEditorEvent =
        * the previous and current runtime render snapshot. Includes
        * additions, deletions, body edits, reply appends, and
        * resolution-state transitions. Consumers can call
-       * `editorRef.current.getComments()` to obtain the full updated
-       * `CommentSidebarSnapshot`.
+       * `editorRef.current.getCommentSidebarSnapshot()` to obtain the full
+       * updated `CommentSidebarSnapshot`.
        *
        * The array is always non-empty when this event fires. When the
        * snapshot's `comments` reference is unchanged between commits,
@@ -2760,6 +3121,13 @@ export type WordReviewEditorEvent =
       documentId: string;
       command: string;
       reasons: WorkflowBlockedCommandReason[];
+      /**
+       * v2.0.0 — per-reason diagnostic composite. When present, carries
+       * one {@link EditorDiagnostic} per entry in `reasons` (matching
+       * indices). Older snapshots may omit this field; LLM consumers
+       * should tolerate absence.
+       */
+      diagnostics?: EditorDiagnostic[];
     }
   | WordReviewEditorPasteEvent
   | {
@@ -3055,8 +3423,25 @@ export interface ChartPreviewResolveParams {
 }
 
 export interface EditorHostAdapter {
+  /**
+   * Called once at load time to retrieve a previously-saved session
+   * blob. Rejections are treated as fatal load failures and surfaced
+   * via the `onError` callback with `code: "host_load_failed"`. The
+   * editor does not retry.
+   */
   load?(params: LoadRequest): Promise<LoadResult>;
+  /**
+   * Called after each debounce window when the in-memory session state
+   * has changed. Rejections are non-fatal: the editor emits
+   * `autosave_state { status: "error" }` and retries on the next dirty
+   * commit. Must be idempotent.
+   */
   saveSession?(params: SaveSessionParams): Promise<SaveSessionResult>;
+  /**
+   * Called when the user triggers an explicit export. Rejections
+   * propagate as a rejected `Promise<ExportResult>` from `exportDocx()`
+   * — the host is responsible for surfacing the error to the user.
+   */
   saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
   logEvent?(event: EditorTelemetryEvent): void;
   /**
@@ -3071,6 +3456,10 @@ export interface EditorHostAdapter {
    * for a PNG magic number, `image/svg+xml` otherwise. Hosts that
    * need a different content type should extend this contract in a
    * follow-up.
+   *
+   * Rejections and thrown exceptions are caught by the editor and
+   * treated identically to a `null` return — the badge fallback path
+   * activates and the error is logged non-fatally.
    */
   renderChartPreview?(params: ChartPreviewResolveParams): Promise<Uint8Array | null>;
 }
@@ -3082,6 +3471,404 @@ export interface EditorDatastoreAdapter {
   logEvent?(event: EditorTelemetryEvent): void;
 }
 
+// ---------------------------------------------------------------------------
+// v2.x — Lane 8 Track H agent-helper widening (Phase 1: types only)
+//
+// Derived from the CLM workblock (`docs/CLM (10).yaml`) hand-rolled patterns:
+// `snapshot_to_projection`, back-to-front anchor-sorted field fill,
+// `change_id → range` walking, and read-merge-write workflow-overlay
+// annotation. See `docs/wiki/agent-helpers.md` for the narrative and
+// `docs/plans/lane-8-api-ergonomics.md` § Track H for the phased plan.
+//
+// Phase 1 ships type declarations and optional method signatures on
+// `WordReviewEditorRef`; runtime wiring lands in Phase 2, Python parity
+// in Phase 3.
+// ---------------------------------------------------------------------------
+
+/**
+ * Options controlling the shape of the annotated-text projection returned
+ * by {@link WordReviewEditorRef.getRenderSnapshotAsText} /
+ * {@link EditorSurfaceSnapshotLike.toAnnotatedText}.
+ *
+ * All flags default to `true`; callers who only want the raw text can
+ * opt everything off to skip the post-processing cost.
+ */
+export interface TextProjectionOptions {
+  /**
+   * When `true` (default), every line in {@link TextProjection.lines}
+   * carries the `[start, end)` runtime offsets the line spans in the
+   * active story. Offsets are the same unit `findAllText` / `replaceText`
+   * / `addScope` accept, so agent code can feed offsets back into
+   * mutation calls without re-projection.
+   */
+  withOffsets?: boolean;
+  /**
+   * When `true` (default), {@link TextProjection.lines} is populated.
+   * When `false`, only {@link TextProjection.text} is computed; useful
+   * for regex search where line boundaries don't matter.
+   */
+  withLineMap?: boolean;
+  /**
+   * When `true` (default), {@link TextProjection.stories} is populated
+   * with one entry per non-main story (header/footer/footnote/endnote)
+   * that carries its own offset space. Set `false` to skip secondary
+   * stories entirely — main body only.
+   */
+  withStoryMap?: boolean;
+  /**
+   * Restrict projection to a specific story. Defaults to main body.
+   * Unknown story targets return an empty projection (no throw).
+   */
+  storyTarget?: EditorStoryTarget;
+}
+
+/**
+ * A single line within an annotated text projection. Lines are produced
+ * by the same line-segmentation logic that backs `findAllText`'s
+ * `matchLocation.lineIndex`, so agents can round-trip between
+ * `findAllText` results and line indices deterministically.
+ */
+export interface TextProjectionLine {
+  /** Zero-based line index within the containing story. */
+  lineIndex: number;
+  /** Line text, without trailing newline. */
+  text: string;
+  /**
+   * `[start, end)` runtime offsets this line spans. End is exclusive
+   * of any trailing newline. Present only when
+   * {@link TextProjectionOptions.withOffsets} is `true`.
+   */
+  start?: number;
+  end?: number;
+  /** Block id the line belongs to, when derivable. */
+  blockId?: string;
+  /** Story the line belongs to; defaults to main body. */
+  storyTarget?: EditorStoryTarget;
+}
+
+/**
+ * Per-story section of a text projection. Main body is returned on the
+ * top-level {@link TextProjection} fields; non-main stories each get one
+ * entry here with their own offset space.
+ */
+export interface TextProjectionStoryEntry {
+  storyTarget: EditorStoryTarget;
+  text: string;
+  lines?: TextProjectionLine[];
+}
+
+/**
+ * Annotated linear-text projection of the render snapshot. Replaces the
+ * hand-written `snapshot_to_projection` / `workblock.cdr` wrapper that
+ * CLM workblocks carry today. Text is in the same offset space as
+ * `findAllText`, `replaceText`, and `addScope` ranges, so agent code
+ * can search the flattened text, then feed the matching offsets
+ * directly back into mutation APIs.
+ */
+export interface TextProjection {
+  /** Main-body text, newline-separated. */
+  text: string;
+  /** Main-body line map (absent when `withLineMap: false`). */
+  lines?: TextProjectionLine[];
+  /** Non-main-body stories (absent when `withStoryMap: false`). */
+  stories?: TextProjectionStoryEntry[];
+  /**
+   * Total line count across main + stories. Stable even when
+   * `withLineMap: false` (counted without emitting the array).
+   */
+  totalLines: number;
+}
+
+/**
+ * Typed handle for a tracked change or comment thread as returned by
+ * {@link WordReviewEditorRef.findChangeById} /
+ * {@link WordReviewEditorRef.findAllChanges}. Collapses the current
+ * two-step `getComments() → .threads` + `getTrackedChanges() → .revisions`
+ * walk that CLM's `_get_range_from_diff_items` / `_get_range_from_doc`
+ * open-codes today.
+ */
+export interface ChangeAnchor {
+  kind: "comment" | "revision";
+  /** `commentId` (when `kind === "comment"`) or `revisionId`. */
+  id: string;
+  /**
+   * Best-known live anchor. For comments: the thread anchor. For
+   * revisions: `anchor.range` (fresh) or `anchor.lastKnownRange`
+   * (detached). Consumers should treat detached anchors as advisory.
+   */
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+  /** `false` when the underlying thread/revision is detached. */
+  isLive: boolean;
+}
+
+/**
+ * Filter for {@link WordReviewEditorRef.findAllChanges}. AND-combined;
+ * omitted fields do not constrain the result.
+ */
+export interface ChangeFilter {
+  kind?: "comment" | "revision";
+  storyTarget?: EditorStoryTarget;
+  authorId?: string;
+  /** Only return changes authored at/after this revision token. */
+  sinceRevisionToken?: string;
+  /** Only return live (non-detached) changes. Defaults to `false`. */
+  liveOnly?: boolean;
+}
+
+/**
+ * One edit in a {@link WordReviewEditorRef.applyBatchedEdits} batch.
+ * Discriminated by `kind`. Each shape mirrors an existing ref method
+ * (`replaceText`, `insertFragment`, `setFontFamily`-style mark ops).
+ */
+export type BatchEditOperation =
+  | {
+      kind: "replace-text";
+      target: EditorAnchorProjection;
+      text: string;
+      formatting?: TextFormattingDirective;
+    }
+  | {
+      kind: "insert-fragment";
+      target: EditorAnchorProjection;
+      fragment: CanonicalDocumentFragment;
+    }
+  | {
+      kind: "set-mark";
+      target: EditorAnchorProjection;
+      mark: TextMark;
+    }
+  | {
+      kind: "clear-mark";
+      target: EditorAnchorProjection;
+      mark: TextMark["type"];
+    };
+
+/**
+ * Sequencing contract for {@link WordReviewEditorRef.applyBatchedEdits}.
+ *
+ * - `"back-to-front"`: edits are sorted by descending `target.range.to`
+ *   before apply, so earlier offsets are not shifted by later edits.
+ *   Use for field-fill / find-and-replace workflows. Default.
+ * - `"atomic"`: edits are applied in array order inside a single
+ *   `startAction("batch")` bracket; any failure rolls back the
+ *   whole batch via a single `undo()`.
+ */
+export interface BatchEditOptions {
+  mode?: "back-to-front" | "atomic";
+  /** Optional label for the action bracket; surfaces in undo UX. */
+  actionLabel?: string;
+}
+
+export interface BatchEditEntryResult {
+  ok: boolean;
+  /** Diagnostic (recoverable skip) when `ok === false`. */
+  diagnostic?: EditorDiagnostic;
+}
+
+export interface BatchEditResult {
+  appliedCount: number;
+  skippedCount: number;
+  entries: BatchEditEntryResult[];
+}
+
+/**
+ * Differential patch for {@link WorkflowOverlay}. Replaces the
+ * read-merge-write pattern documented in `public-api.md` under
+ * `getWorkflowOverlay()`. Runtime-authored fields (`scopes` from
+ * `addScope`, `workItems`) are never clobbered; only the fields
+ * named in the patch are touched.
+ */
+export interface WorkflowOverlayPatch {
+  addScopes?: WorkflowScope[];
+  removeScopeIds?: string[];
+  addCandidates?: WorkflowCandidateRange[];
+  removeCandidateIds?: string[];
+  /** Shallow-merge into existing work items by `workItemId`. */
+  mergeWorkItems?: WorkflowWorkItem[];
+  /**
+   * When set, overlay-level `metadataPersistence` is replaced. Omit to
+   * leave the current value alone.
+   */
+  metadataPersistence?: MetadataPersistenceMode;
+}
+
+/**
+ * Input shape for {@link WordReviewEditorRef.attachAiExplanationScope}.
+ * Collapses the "find change → build scope → patch overlay" sequence
+ * CLM workblocks hand-roll in `annotate_document_with_explanations`.
+ */
+export interface AiExplanationScopeInput {
+  /** `commentId` or `revisionId` to anchor the explanation against. */
+  changeId: string;
+  explanation: {
+    summary: string;
+    detail?: string;
+    riskLevel?: "low" | "medium" | "high" | "unknown";
+    recommendedAction?: "accept" | "reject" | "review" | "escalate";
+    actionRationale?: string;
+    /** Free-form location label (e.g., "§4.2 payment terms"). */
+    location?: string;
+  };
+  /** Scope mode. Defaults to `"view"` — advisory-only. */
+  mode?: WorkflowScopeMode;
+  /** Optional caller-supplied scope id; runtime mints one when absent. */
+  scopeId?: string;
+  /** Domain tag. Defaults to `"ai-suggestion"`. */
+  domain?: string;
+}
+
+export interface AiExplanationScopeResult {
+  scopeId: string;
+  candidateId: string;
+  anchor: EditorAnchorProjection;
+}
+
+// ---------------------------------------------------------------------------
+// v2.0.0 — Track D purpose-grouped ref projections
+// ---------------------------------------------------------------------------
+
+/**
+ * Ergonomic projection of comment-related methods. Pure dispatch over
+ * {@link WordReviewEditorRef} — flat methods keep working. LLM workblocks
+ * and wrapper layers should prefer the projection to narrow the surface
+ * they import.
+ */
+export interface WordReviewEditorCommentsFacet {
+  add(params: AddCommentParams): AddCommentResult;
+  addReply(commentId: string, body: string): AddCommentReplyResult | null;
+  resolve(commentId: string): void;
+  reopen(commentId: string): void;
+  edit(commentId: string, body: string): void;
+  delete(commentId: string): void;
+  open(commentId: string): void;
+  scrollTo(commentId: string): void;
+  get(): CommentSidebarSnapshot;
+  /**
+   * Track H (v2.x Phase 1 — types only; runtime wired in Phase 2). Typed
+   * id lookup over `get().threads`. Returns `null` when the id is unknown.
+   */
+  getById?(commentId: string): CommentSidebarThreadSnapshot | null;
+}
+
+/** Ergonomic projection of tracked-change methods. */
+export interface WordReviewEditorChangesFacet {
+  accept(changeId: string): void;
+  reject(changeId: string): void;
+  acceptAll(): void;
+  rejectAll(): void;
+  acceptGroup(groupId: string): void;
+  rejectGroup(groupId: string): void;
+  scrollTo(revisionId: string): void;
+  get(): TrackedChangesSnapshot;
+  getSuggestions(): SuggestionsSnapshot;
+  /**
+   * Track H (v2.x Phase 1 — types only; runtime wired in Phase 2). Typed
+   * id lookup over `get().revisions`. Returns `null` when unknown.
+   */
+  getById?(revisionId: string): TrackedChangeEntrySnapshot | null;
+  /**
+   * Track H — unified change-lookup across comments + revisions. Replaces
+   * the hand-rolled `_get_range_from_diff_items` walk.
+   */
+  findById?(changeId: string): ChangeAnchor | null;
+  /** Track H — filter over all comments + revisions. */
+  findAll?(filter?: ChangeFilter): ChangeAnchor[];
+}
+
+/** Ergonomic projection of field / TOC operations. */
+export interface WordReviewEditorFieldsFacet {
+  getSnapshot(): FieldSnapshot;
+  update(options?: UpdateFieldsOptions): UpdateFieldsResult;
+  updateToc(options?: TocRefreshOptions): TocRefreshResult;
+}
+
+/** Ergonomic projection of document-level operations. */
+export interface WordReviewEditorDocumentFacet {
+  export(options?: ExportDocxOptions): Promise<ExportResult>;
+  getSessionState(): EditorSessionState;
+  getSnapshot(): PersistedEditorSnapshot;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  isDirty(): boolean;
+  getCompatibilityReport(): CompatibilityReport;
+  getStats(): DocumentStats;
+  /**
+   * Track H (v2.x Phase 1 — types only; runtime wired in Phase 2).
+   * Annotated linear-text projection with stable runtime offsets.
+   * Replaces the hand-written `snapshot_to_projection` helper.
+   */
+  getAsText?(options?: TextProjectionOptions): TextProjection;
+  /**
+   * Track H — sequenced replace/insert/mark batch with offset-shift
+   * protection. Collapses the back-to-front sort + bytes-chain pattern
+   * from CLM's `generate_filled_document`.
+   */
+  applyBatchedEdits?(
+    edits: BatchEditOperation[],
+    options?: BatchEditOptions,
+  ): Promise<BatchEditResult>;
+  /**
+   * Track H — one-shot `patchWorkflowOverlay` + `exportDocx`. Use for
+   * AI-annotation pipelines that would otherwise run two stateless
+   * round-trips through the same document.
+   */
+  exportWithOverlayPatch?(
+    patch: WorkflowOverlayPatch,
+    exportOptions?: ExportDocxOptions,
+  ): Promise<ExportResult>;
+}
+
+/**
+ * Ergonomic projection of workflow-scope query methods. Phase C+ LLM
+ * helpers (`adjust`, `resize`, `alignToBoundary`, `addForText`,
+ * `applyPlaybook`, `getRenderProjection`) will be added additively as
+ * the underlying ref methods merge from the Phase C+ lane.
+ */
+export interface WordReviewEditorScopesFacet {
+  add(params: AddScopeParams): AddScopeResult;
+  get(scopeId: string): WorkflowScope | null;
+  remove(scopeId: string): void;
+  query(filter?: ScopeQueryFilter): ScopeQueryResult[];
+  findAt(
+    position: EditorAnchorProjection,
+    options?: { includeHidden?: boolean; includeInvisible?: boolean },
+  ): ScopeQueryResult[];
+  findIntersecting(
+    range: EditorAnchorProjection,
+    options?: {
+      includeHidden?: boolean;
+      includeInvisible?: boolean;
+      mode?: "overlap" | "contain";
+    },
+  ): ScopeQueryResult[];
+  /**
+   * Track H (v2.x Phase 1 — types only; runtime wired in Phase 2).
+   * Differential overlay patch. Never clobbers engine-authored scopes
+   * or work items — only the fields named in the patch are touched.
+   */
+  patch?(patch: WorkflowOverlayPatch): void;
+  /**
+   * Track H — one-shot convenience: resolve `changeId` via
+   * `findChangeById`, build an AI-explanation scope + candidate, and
+   * patch the overlay. Collapses ~60 lines of CLM workblock glue.
+   */
+  attachAiExplanation?(input: AiExplanationScopeInput): AiExplanationScopeResult;
+}
+
+/**
+ * Ergonomic projection of diagnostic surfaces. Exposes the legacy warning
+ * array plus the v2.0.0 code catalog for LLM consumers that want to
+ * discover remediation strategies up front (before an error fires).
+ */
+export interface WordReviewEditorDiagnosticsFacet {
+  getWarnings(): EditorWarning[];
+  getCatalog(): ReadonlyArray<{
+    code: EditorDiagnosticCode;
+    severity: "fatal" | "error" | "warning" | "info";
+    llmMetadata: EditorDiagnosticLlmMetadata;
+  }>;
+}
+
 export interface WordReviewEditorRef {
   focus(): void;
   blur(): void;
@@ -3091,7 +3878,17 @@ export interface WordReviewEditorRef {
   openComment(commentId: string): void;
   resolveComment(commentId: string): void;
   reopenComment(commentId: string): void;
-  addCommentReply(commentId: string, body: string): AddCommentReplyResult;
+  /**
+   * Append a reply entry to an existing thread. Returns `{ commentId,
+   * entryId }` on success and `null` when the thread is unknown, resolved,
+   * or detached — in that case a `review_target_not_found` warning fires
+   * on `onWarning` / `warning_added` with `details.op = "addCommentReply"`
+   * and `details.reason` ∈ `{ "comment_unknown", "comment_status" }`.
+   */
+  addCommentReply(
+    commentId: string,
+    body: string,
+  ): AddCommentReplyResult | null;
   editCommentBody(commentId: string, body: string): void;
   deleteComment(commentId: string): void;
   /**
@@ -3112,6 +3909,34 @@ export interface WordReviewEditorRef {
    * metadata record. No-op when the scopeId is unknown.
    */
   removeScope(scopeId: string): void;
+  /**
+   * §C8 — Convenience: adds a scope with `visibility: "invisible"` atomically.
+   * Mode defaults to `"comment"` — invisible scopes carry no InteractionGuard
+   * constraint unless `mode: "view"` is passed explicitly.
+   */
+  addInvisibleScope(
+    params: Omit<AddScopeParams, "mode"> & { mode?: WorkflowScopeMode },
+  ): AddScopeResult;
+  /**
+   * §C8 — Set a scope's visibility. Collab-replicated; all peers see the same
+   * chrome state after the next overlay-replay cycle.
+   */
+  setScopeVisibility(scopeId: string, visibility: ScopeVisibility): void;
+  /**
+   * §C8 — Get a scope's current visibility. Returns `"visible"` for unknown
+   * scopes or when the `visibility` field has never been set.
+   */
+  getScopeVisibility(scopeId: string): ScopeVisibility;
+  /**
+   * §C7 — Set the local chrome-visibility state. Local view-state only —
+   * never collab-replicated. Controls whether the scope rail / decorations
+   * render in the current session.
+   */
+  setScopeChromeVisibility(state: ScopeChromeVisibilityState): void;
+  /**
+   * §C7 — Get the local chrome-visibility state. Default is `{ mode: "all" }`.
+   */
+  getScopeChromeVisibility(): ScopeChromeVisibilityState;
   acceptChange(changeId: string): void;
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
@@ -3144,7 +3969,9 @@ export interface WordReviewEditorRef {
   getCommentSidebarSnapshot(): CommentSidebarSnapshot;
   getTrackedChangesSnapshot(): TrackedChangesSnapshot;
   getSuggestionsSnapshot(): SuggestionsSnapshot;
+  /** @deprecated Use {@link getCommentSidebarSnapshot} instead. */
   getComments(): CommentSidebarSnapshot;
+  /** @deprecated Use {@link getTrackedChangesSnapshot} instead. */
   getTrackedChanges(): TrackedChangesSnapshot;
   isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
@@ -3251,7 +4078,7 @@ export interface WordReviewEditorRef {
   setCellBackground(color: string): void;
   search(query: string, options?: SearchOptions): SearchResultSnapshot[];
   clearSearch(): void;
-  setSelection(selection: SelectionSnapshot | null): void;
+  setSelection(selection: SelectionSnapshot | null, options?: SetSelectionOptions): void;
   scrollToRevision(revisionId: string): void;
   scrollToComment(commentId: string): void;
   openStory(target: EditorStoryTarget): void;
@@ -3326,6 +4153,124 @@ export interface WordReviewEditorRef {
   setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /**
+   * Phase C §C1 — filter + project the current workflow overlay into a
+   * scope-joined view. Reads a snapshot of the current overlay + metadata
+   * entries + work items; no mutation. Results are sorted by start-marker
+   * document position, tie-broken by `scopeId` ascending.
+   *
+   * Defaults: `storyTarget` = `{ kind: "main" }` (pass `"*"` for any
+   * story); `includeHidden` / `includeInvisible` default to `false`
+   * (§C8 additive — accepted today but no-ops until `visibility` lands).
+   *
+   * Returns `[]` when no workflow overlay has been set.
+   */
+  queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[];
+  /**
+   * Phase C §C1 — live subscription to `queryScopes(filter)` results.
+   * Fires the callback immediately, then once per settled commit after any
+   * overlay change that passes the filter. Multiple changes in one
+   * synchronous burst are coalesced into a single callback via `setTimeout(0)`.
+   * Shallow-equality dedup: callback skips if results are unchanged.
+   * Returns an unsubscribe function.
+   */
+  subscribeToScopeQuery(
+    filter: ScopeQueryFilter,
+    callback: (results: ScopeQueryResult[]) => void,
+  ): () => void;
+  /**
+   * Phase C §C2 — every scope whose marker range contains `position.from`
+   * (end-inclusive), ordered outermost → innermost. Pass a zero-length
+   * range (`from === to`) for a point query. Returns the full
+   * `ScopeQueryResult` (scope + entries + workItem) so results compose
+   * directly with `setSelection`, `addScope`, `getLocationForAnchor`.
+   *
+   * Companion to `getInteractionGuardSnapshot().matchedScopeId` — that
+   * API returns the innermost-only match; this one returns the whole
+   * enclosing stack.
+   */
+  findScopesAt(
+    position: EditorAnchorProjection,
+    options?: { includeHidden?: boolean; includeInvisible?: boolean },
+  ): ScopeQueryResult[];
+  /**
+   * Phase C §C2 — every scope whose marker range intersects `range`
+   * (accepts a range anchor; non-range anchors yield `[]`). Default
+   * `mode: "overlap"` matches any intersection including touching
+   * endpoints; `mode: "contain"` requires the scope's entire range to
+   * sit within `range`. Deterministic order by start-marker position.
+   */
+  findScopesIntersecting(
+    range: EditorAnchorProjection,
+    options?: {
+      includeHidden?: boolean;
+      includeInvisible?: boolean;
+      mode?: "overlap" | "contain";
+    },
+  ): ScopeQueryResult[];
+  /**
+   * Phase C §C3 — find the first text match in the document.
+   * Supports `regex`, `inScope`, `inStory` options.
+   * Throws `EditorApiError({ code: "search_invalid_regex" })` synchronously
+   * when `options.regex === true` and `query` is not a valid regex pattern.
+   * Returns `null` when no match is found.
+   */
+  findFirstText(
+    query: string,
+    options?: SearchOptions,
+  ): EditorAnchorProjection | null;
+  /**
+   * Phase C §C3 — find all text matches in the document.
+   * Same options and error contract as `findFirstText`.
+   * Returns `[]` when no matches are found.
+   */
+  findAllText(
+    query: string,
+    options?: SearchOptions,
+  ): EditorAnchorProjection[];
+  /**
+   * Phase C §C3 — find first text match and select it. Returns `true` if a
+   * match was found (and selection updated), `false` otherwise.
+   */
+  selectFirstText(
+    query: string,
+    options?: SearchOptions & SetSelectionOptions,
+  ): boolean;
+  /**
+   * Phase C §C3 — select first text match and return the total match count.
+   * Returns `0` when no matches are found. Multi-range selection deferred
+   * to Lane 1 shipping `SelectionSnapshot.multi`.
+   */
+  selectAllText(
+    query: string,
+    options?: SearchOptions & SetSelectionOptions,
+  ): number;
+  /**
+   * Phase C §C4 — find all text matches that also satisfy the given style
+   * filter. Combines `findAllText` text search with paragraph-level and
+   * run-level formatting predicates:
+   *   - `inHeading`: paragraph must be a heading (outlineLevel set or styleId
+   *     matches /^Heading\d/i).
+   *   - `hasFormatting`: ALL segments in the match must carry ALL specified
+   *     formatting marks (AND semantics per property, AND across segments).
+   *   - `anyFormatting`: ALL segments in the match must carry AT LEAST ONE of
+   *     the specified marks (OR semantics per property, AND across segments).
+   * An empty filter is a no-op — returns all text matches.
+   */
+  findTextWithStyle(
+    query: string,
+    filter: TextStyleFilter,
+    options?: SearchOptions,
+  ): EditorAnchorProjection[];
+  /**
+   * Phase C §C4 — convenience wrapper: `findTextWithStyle` + select the first
+   * result. Returns the total match count (0 when no matches).
+   */
+  selectTextWithStyle(
+    query: string,
+    filter: TextStyleFilter,
+    options?: SearchOptions & SetSelectionOptions,
+  ): number;
   /**
    * Schema 1.1 — set the overlay default for metadata persistence.
    * Author-only per collab-master-plan §7 role-gating matrix;
@@ -3370,7 +4315,9 @@ export interface WordReviewEditorRef {
    * `"external"`, call `resolver.resolve(ref)`, inline the returned
    * value, clear `storageRef`, preserve `metadataVersion` as a hint.
    * Call this before exporting a docx outside the resolver's reach
-   * (e.g., sending to an external supplier).
+   * (e.g., sending to an external supplier). Rejects if
+   * `resolver.resolve` throws for any entry; partial conversions are
+   * rolled back.
    */
   convertScopesToInternal(scopeIds: string[]): Promise<void>;
   /**
@@ -3409,6 +4356,8 @@ export interface WordReviewEditorRef {
   /**
    * Re-attempt any persists that failed since the last successful
    * write.  Pass a namespace to scope the retry; omit to retry all.
+   * Rejects if the persister throws on retry; the failed namespace
+   * remains in the pending queue.
    */
   retryPendingPersist(namespace?: EditorStateNamespace): Promise<void>;
   setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
@@ -3425,6 +4374,92 @@ export interface WordReviewEditorRef {
     query?: RuntimeContextAnalyticsQuery,
   ): RuntimeContextAnalyticsSnapshot | null;
 
+  // -------------------------------------------------------------------------
+  // Track H — agent-helper widening (v2.x Phase 1: optional; wired Phase 2)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Track H T1 — annotated linear-text projection with stable runtime
+   * offsets. Replaces the hand-written `snapshot_to_projection` helper
+   * that CLM workblocks carry in `workblock.cdr`.
+   *
+   * **Status:** @experimental (v2.x). Types land in Phase 1; runtime
+   * wiring in Phase 2.
+   */
+  getRenderSnapshotAsText?(options?: TextProjectionOptions): TextProjection;
+  /**
+   * Track H T2 — typed lookup by `commentId` or `revisionId` across
+   * comments + tracked changes. Returns `null` when the id is unknown.
+   * Collapses the two-step walk over `getComments().threads` +
+   * `getTrackedChanges().revisions` that agents currently open-code.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  findChangeById?(changeId: string): ChangeAnchor | null;
+  /**
+   * Track H T2 — filtered enumeration over comments + revisions.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  findAllChanges?(filter?: ChangeFilter): ChangeAnchor[];
+  /**
+   * Track H T10 — typed id lookup over the comment sidebar snapshot.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  getCommentSnapshotById?(commentId: string): CommentSidebarThreadSnapshot | null;
+  /**
+   * Track H T10 — typed id lookup over the tracked-changes snapshot.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  getRevisionSnapshotById?(revisionId: string): TrackedChangeEntrySnapshot | null;
+  /**
+   * Track H T3 — sequenced batch of replace/insert/mark operations with
+   * offset-shift protection. In `"back-to-front"` mode (default), edits
+   * are sorted by descending `target.range.to` before apply so earlier
+   * offsets are not shifted by later edits. In `"atomic"` mode the batch
+   * runs inside a single `startAction` bracket and rolls back on failure.
+   * Replaces the manual bytes-chain + sort pattern from CLM's
+   * `generate_filled_document`.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  applyBatchedEdits?(
+    edits: BatchEditOperation[],
+    options?: BatchEditOptions,
+  ): Promise<BatchEditResult>;
+  /**
+   * Track H T4 — differential `WorkflowOverlay` patch. Never clobbers
+   * engine-authored `scopes` or `workItems`; only the fields named in
+   * the patch are touched. Replaces the documented read-merge-write
+   * pattern around `getWorkflowOverlay()` + `setWorkflowOverlay()`.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  patchWorkflowOverlay?(patch: WorkflowOverlayPatch): void;
+  /**
+   * Track H T5 — resolve `changeId` via `findChangeById`, build an
+   * AI-explanation scope + candidate, and patch the overlay. One call
+   * replaces ~60 lines of `annotate_document_with_explanations` glue.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  attachAiExplanationScope?(
+    input: AiExplanationScopeInput,
+  ): AiExplanationScopeResult;
+  /**
+   * Track H T6 — one-shot `patchWorkflowOverlay` + `exportDocx`. Use
+   * for AI-annotation pipelines that would otherwise run two stateless
+   * round-trips through the same document.
+   *
+   * **Status:** @experimental (v2.x Phase 1).
+   */
+  exportDocxFromOverlayedSession?(
+    patch: WorkflowOverlayPatch,
+    exportOptions?: ExportDocxOptions,
+  ): Promise<ExportResult>;
+
   /**
    * Runtime-owned layout facet.
    *
@@ -3444,6 +4479,26 @@ export interface WordReviewEditorRef {
    * `ref.tables.apply(op)` with a typed discriminated union.
    */
   readonly tables: WordReviewEditorTablesFacet;
+  /**
+   * v2.0.0 — purpose-grouped projection of comment methods. Flat methods
+   * (`addComment`, `resolveComment`, …) keep working. LLM workblocks should
+   * prefer `editor.comments.*` to narrow their imports.
+   */
+  readonly comments: WordReviewEditorCommentsFacet;
+  /** v2.0.0 — purpose-grouped projection of tracked-change methods. */
+  readonly changes: WordReviewEditorChangesFacet;
+  /** v2.0.0 — purpose-grouped projection of field / TOC operations. */
+  readonly fields: WordReviewEditorFieldsFacet;
+  /** v2.0.0 — purpose-grouped projection of document-level operations. */
+  readonly document: WordReviewEditorDocumentFacet;
+  /** v2.0.0 — purpose-grouped projection of workflow-scope + LLM helpers. */
+  readonly scopes: WordReviewEditorScopesFacet;
+  /**
+   * v2.0.0 — diagnostic surface including the LLM error-catalog. Prefer
+   * `editor.diagnostics.getCatalog()` at session-start to learn the
+   * retry/fallback strategy for every code the editor can emit.
+   */
+  readonly diagnostics: WordReviewEditorDiagnosticsFacet;
 }
 
 /**
@@ -3508,6 +4563,13 @@ export interface WordReviewEditorChromeOptions {
 export interface WordReviewEditorProps {
   documentId: string;
   currentUser: EditorUser;
+  /**
+   * Optional host-provided shell content mounted above the editor's own
+   * toolbar region. Harnesses and host apps use this to install a
+   * `TwShellHeader` without rendering a parallel chrome outside the
+   * editor workspace.
+   */
+  shellHeader?: ReactNode;
   ydoc?: import('yjs').Doc;
   awareness?: import("y-protocols/awareness").Awareness;
   /**
@@ -3634,8 +4696,23 @@ export interface WordReviewEditorProps {
   hostAdapter?: EditorHostAdapter;
   datastore?: EditorDatastoreAdapter;
   autosave?: AutosaveConfig;
+  /**
+   * Receives every `WordReviewEditorEvent` as it fires. Exceptions
+   * thrown inside this callback are caught and logged non-fatally —
+   * they do not propagate into the editor. Returning a Promise is
+   * allowed but ignored.
+   */
   onEvent?: (event: WordReviewEditorEvent) => void;
+  /**
+   * Receives non-fatal `EditorWarning` objects (e.g., compatibility
+   * issues, detached anchors). Exceptions thrown here are swallowed.
+   */
   onWarning?: (warning: EditorWarning) => void;
+  /**
+   * Receives fatal `EditorError` objects. Called once per error; the
+   * editor enters a degraded state afterward. Exceptions thrown inside
+   * this callback are swallowed to avoid double-fault loops.
+   */
   onError?: (error: EditorError) => void;
   /**
    * Optional: opens the host's sidebar to the tracked-changes panel.  When
@@ -3750,6 +4827,38 @@ export interface WordReviewEditorProps {
    * Capability id: `shortcut.last-edit`.
    */
   onLastEditRequested?: (context: ShortcutDelegationContext) => void;
+  /**
+   * design-close-chrome Phase 2 — density contract (designsystem §4.2).
+   *
+   * Controls the global `data-density` attribute that drives the
+   * `--space-density-multiplier` cascade in `tokens.css`.  When set,
+   * the editor calls `useDensity().setDensity(value)` inside an effect;
+   * when omitted, the hook reads the user's persisted preference from
+   * `localStorage["wre.density"]` (defaulting to `"standard"`).
+   *
+   * @experimental The set of values (`"compact" | "standard" | "comfortable"`)
+   * is stable; the effect-driven attribute write may move into a
+   * theme-provider context in a future major.
+   */
+  density?: "compact" | "standard" | "comfortable";
+  /**
+   * design-close-chrome Phase 4 / R9 — host-supplied selection-tool
+   * registry entries.  Each entry is merged with the default
+   * `SELECTION_TOOL_REGISTRY` via `resolveSelectionToolRegistry` (host
+   * wins on id collision, merged list is precedence-sorted).  Low-
+   * precedence host entries (precedence < 10) can shadow the default
+   * `suggestion-review` slot — useful for integrating a bespoke review
+   * surface while keeping the remaining defaults.
+   *
+   * The entry's `id` must be a known `SelectionToolKind`; widening the
+   * kind union to accept host render functions is coordinated with
+   * Lane 8 (API ergonomics) and not part of this slice.
+   *
+   * @experimental
+   */
+  customSelectionTools?: ReadonlyArray<
+    import("../ui/headless/chrome-registry").SelectionToolRegistryEntry
+  >;
 }
 
 /**
@@ -3863,6 +4972,35 @@ export interface ResolveMetadataConflictInput {
 }
 
 // ---------------------------------------------------------------------------
+// Phase C §C3 — generic editor API error
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown synchronously by query methods when the caller passes an invalid
+ * argument. The `code` field identifies the specific failure:
+ * - `"search_invalid_regex"` — `options.regex === true` and `query` is not
+ *   a valid JavaScript regular expression pattern.
+ */
+export class EditorApiError extends Error {
+  readonly code: string;
+  /**
+   * v2.0.0 dual-error composite. Always populated when the editor itself
+   * throws. Downstream code that re-throws `EditorApiError` (e.g. test
+   * harnesses) may set this to `undefined`.
+   */
+  readonly diagnostic?: EditorDiagnostic;
+  constructor(params: {
+    code: string;
+    message?: string;
+    diagnostic?: EditorDiagnostic;
+  }) {
+    super(params.message ?? `EditorApiError: ${params.code}`);
+    this.name = "EditorApiError";
+    this.code = params.code;
+    this.diagnostic = params.diagnostic;
+  }
+}
+
 // Schema 1.1 — metadata-persistence errors (P17)
 // ---------------------------------------------------------------------------
 
@@ -3872,11 +5010,14 @@ export interface ResolveMetadataConflictInput {
  * Follows the fail-closed policy in collab-master-plan §1.6.
  */
 export class MetadataResolverMissingError extends Error {
-  constructor() {
+  /** v2.0.0 dual-error composite (code `api.metadata_resolver_missing`). */
+  readonly diagnostic?: EditorDiagnostic;
+  constructor(diagnostic?: EditorDiagnostic) {
     super(
       "setMetadataPersistenceMode('external') requires a resolver — call " +
         "setScopeMetadataResolver(...) first.",
     );
     this.name = "MetadataResolverMissingError";
+    this.diagnostic = diagnostic;
   }
 }