@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/api/public-types.ts

@@ -1,10 +1,19 @@
 import type { ReactNode } from "react";
-import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
+import type { ApiV3 } from "./v3/_create.ts";
+import type {
+  DocumentPageSnapshot,
+  EditorStoryTarget,
+  PageLayoutSnapshot,
+} from "../model/layout/page-layout-snapshot.ts";
+import type {
+  CanonicalDocumentEnvelope,
+  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";
 import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
 import type { RenderFrameRect } from "../runtime/render/index.ts";
-import type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
+import type { ScopeRailPosture } from "../runtime/workflow/rail/compose.ts";
 import type { SharedWorkflowState } from "../runtime/collab/workflow-shared.ts";
 import type {
   MetadataPersistenceMode,
@@ -50,6 +59,66 @@ export type {
 
 export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
 export type { SharedWorkflowState };
+/**
+ * Re-exported for Layer-11 presentation surfaces (refactor/11 Slice 5
+ * retirement) so the PM mount + surrounding surfaces consume the
+ * canonical-envelope type through the public API seam instead of
+ * reaching into `src/core/state/editor-state.ts`.
+ */
+export type { CanonicalDocumentEnvelope };
+
+/**
+ * Chart types re-exported for Layer-11 chart renderers (refactor/11
+ * Slice 6 retirement).  The chart-family presentation (area / bar /
+ * bubble / line / pie / scatter / combo / unsupported / svg-primitives)
+ * consumes the shape definitions through the public API seam instead
+ * of reaching into `src/model/chart-types.ts` or
+ * `src/io/ooxml/chart/types.ts`.  Value imports (color resolution,
+ * palette, style-table builders) are out of scope — those remain under
+ * `src/io/ooxml/chart/**` and their Layer-11 usages stay in the
+ * exception register until a dedicated chart API is introduced.
+ */
+export type * from "../model/chart-types.ts";
+export type { ResolvedTheme } from "../model/canonical-document.ts";
+
+/**
+ * Workflow-rail types re-exported for the Layer-11 scope-rail + scope-
+ * card overlays (refactor/11 Slice 6 retirement).  `WorkflowFacet` +
+ * `ScopeRailSegment` are the canonical types the overlays consume;
+ * `ScopeRailPosture` is already re-exported above.
+ */
+export type {
+  WorkflowFacet,
+  ScopeRailSegment,
+} from "../runtime/workflow/rail/types.ts";
+
+/**
+ * Substrate-type re-exports consumed by Layer-11 overlay + chrome
+ * surfaces (refactor/11 type-only retirement sweep). Every entry below
+ * exists because a presentation file previously imported it directly
+ * from `src/runtime/**` or `src/model/**`; routing through the public-
+ * types choke point (per the L08 adversarial-close pattern) preserves
+ * the type seam without the boundary-guard reach-through.
+ */
+export type { CollabSession } from "../runtime/collab-session.ts";
+export type { MetadataIntegrity } from "../runtime/workflow/tamper-gate.ts";
+export type { ScopeTagRegistry } from "../runtime/workflow/scope-tag-registry.ts";
+// Semantic-scope shapes — re-exported so L10 (ui.scope.*) + L09
+// (ai.getScopeBundle) + L11 (scope-card consumers) can import the
+// canonical types from the public-types choke point instead of
+// reaching into `src/runtime/scopes/**` (blocked by L10's layer-purity
+// CI guard). Authoritative definitions live at
+// `src/runtime/scopes/semantic-scope-types.ts`.
+export type {
+  ScopeBundle,
+  ScopeBundleEvidence,
+  ScopeBundleNeighborhood,
+  ScopeHandle,
+  SemanticScope,
+  SemanticScopeKind,
+} from "../runtime/scopes/semantic-scope-types.ts";
+export type { GeometryFacet } from "../runtime/geometry/index.ts";
+export type { RuntimePageGraph } from "../runtime/layout/page-graph.ts";
 
 export type {
   WordReviewEditorLayoutFacet,
@@ -106,7 +175,12 @@ export type {
 
 // 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 { ScopeRailPosture } from "../runtime/workflow/rail/compose.ts";
+
+// refactor/11 Track G — re-export SessionCapabilities so presentation
+// code can consume the runtime-derived capability shape without
+// reaching into `src/runtime/**` directly (P3).
+export type { SessionCapabilities } from "../runtime/session-capabilities.ts";
 
 export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
 export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
@@ -168,22 +242,43 @@ export type EditorAnchorProjection =
       reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
     };
 
-export type EditorStoryTarget =
-  | { kind: "main" }
-  | {
-      kind: "header";
-      relationshipId: string;
-      variant: "default" | "first" | "even";
-      sectionIndex?: number;
-    }
-  | {
-      kind: "footer";
-      relationshipId: string;
-      variant: "default" | "first" | "even";
-      sectionIndex?: number;
-    }
-  | { kind: "footnote"; noteId: string }
-  | { kind: "endnote"; noteId: string };
+/**
+ * Re-exported from `src/model/layout/page-layout-snapshot.ts`. The
+ * canonical declaration moved there in refactor/04 cross-layer-coord
+ * §1.12 Pass 2 so `RuntimePageGraph` can live in a layer reachable from
+ * session / stateless services without transiting `src/runtime/**`.
+ */
+export type { EditorStoryTarget } from "../model/layout/page-layout-snapshot.ts";
+
+/**
+ * Story-target equality helper — re-exported at the public-types boundary
+ * so Layer-11 presentation consumers (e.g. `remote-cursor-plugin.ts`) can
+ * compare `EditorStoryTarget` values without reaching into
+ * `src/core/selection/mapping.ts` directly. Pure function over public
+ * types; canonical implementation lives on the core selection module.
+ * Shipped 2026-04-23 via coord-07 §2.1 collab-expansion remainder.
+ */
+export { storyTargetsEqual, MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+
+/**
+ * OOXML unit-conversion constants shared with presentation-layer
+ * renderers. EMU (English Metric Units) is the OOXML measurement
+ * unit; `EMU_PER_PX` converts to CSS pixels at 96 dpi;
+ * `ROTATION_UNITS_PER_DEGREE` is the c:rot scaling factor;
+ * `PERCENTAGE_PARTS` is the OOXML st:ST_Percentage base (1 / 100000).
+ * Pure constant re-exports of the canonical values on
+ * `src/runtime/units.ts` so shape renderers + PM schema can convert
+ * document-space units without reaching into `src/runtime/**`.
+ * Re-exported 2026-04-23 per coord-11 §4 register cleanup.
+ */
+export {
+  EMU_PER_PX,
+  EMU_PER_INCH,
+  TWIPS_PER_PX,
+  ROTATION_UNITS_PER_DEGREE,
+  PERCENTAGE_PARTS,
+  SRCRECT_UNITS_PER_PERCENT,
+} from "../runtime/units.ts";
 
 export interface SelectionSnapshot {
   anchor: number;
@@ -193,54 +288,11 @@ export interface SelectionSnapshot {
   storyTarget?: EditorStoryTarget;
 }
 
-export interface PageLayoutSnapshot {
-  sectionIndex: number;
-  sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
-  pageWidth: number;
-  pageHeight: number;
-  marginTop: number;
-  marginBottom: number;
-  marginLeft: number;
-  marginRight: number;
-  headerMargin: number;
-  footerMargin: number;
-  gutter: number;
-  orientation: "portrait" | "landscape";
-  columns: number;
-  differentFirstPage: boolean;
-  differentOddEvenPages: boolean;
-  pageNumbering?: {
-    format?: string;
-    start?: number;
-    chapterStyle?: string;
-    chapterSeparator?: string;
-  };
-  lineNumbering?: {
-    countBy?: number;
-    start?: number;
-    distance?: number;
-    restart?: "newPage" | "newSection" | "continuous";
-  };
-  pageBorders?: {
-    top?: { value?: string; size?: number; space?: number; color?: string };
-    left?: { value?: string; size?: number; space?: number; color?: string };
-    bottom?: { value?: string; size?: number; space?: number; color?: string };
-    right?: { value?: string; size?: number; space?: number; color?: string };
-    offsetFrom?: "page" | "text";
-    display?: "allPages" | "firstPage" | "notFirstPage";
-    zOrder?: "front" | "back";
-  };
-  documentGrid?: {
-    type?: "default" | "lines" | "linesAndChars" | "snapToChars";
-    linePitch?: number;
-    charSpace?: number;
-  };
-  columnDefinitions: Array<{ width: number; space?: number }>;
-  equalWidthColumns: boolean;
-  columnSeparator: boolean;
-  headerVariants: Array<{ variant: "default" | "first" | "even"; relationshipId: string }>;
-  footerVariants: Array<{ variant: "default" | "first" | "even"; relationshipId: string }>;
-}
+/**
+ * Re-exported from `src/model/layout/page-layout-snapshot.ts`. See the
+ * `EditorStoryTarget` re-export above for the relocation rationale.
+ */
+export type { PageLayoutSnapshot } from "../model/layout/page-layout-snapshot.ts";
 
 export type WorkspaceMode = "canvas" | "page";
 
@@ -576,21 +628,11 @@ export interface DocumentNavigationSnapshot {
   activeSectionIndex: number;
 }
 
-/** Runtime-derived descriptor for a single logical page. */
-export interface DocumentPageSnapshot {
-  /** Zero-based page index within the whole document. */
-  pageIndex: number;
-  /** Section that owns this page (zero-based). */
-  sectionIndex: number;
-  /** Zero-based page index within its owning section. */
-  pageInSection: number;
-  /** Estimated character offset where the page begins in the main story. */
-  startOffset: number;
-  /** Estimated character offset where the page ends in the main story. */
-  endOffset: number;
-  /** Page layout properties inherited from the section. */
-  layout: PageLayoutSnapshot;
-}
+/**
+ * Re-exported from `src/model/layout/page-layout-snapshot.ts`. See the
+ * `EditorStoryTarget` re-export above for the relocation rationale.
+ */
+export type { DocumentPageSnapshot } from "../model/layout/page-layout-snapshot.ts";
 
 /** A heading entry in the document outline. */
 export interface DocumentHeadingSnapshot {
@@ -931,6 +973,29 @@ export type SurfaceInlineSegment =
       hyperlinkHref?: string;
       /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Populated in `src/runtime/surface-projection.ts` via `resolveEffectiveRunFormatting`. Present only when the resolved cascade has at least one field. */
       resolvedRunFormatting?: CanonicalRunFormatting;
+      /**
+       * Layer-03 F6 revision-display posture flags. Populated when
+       * `createEditorSurfaceSnapshot` is called with
+       * `{ revisionMarkupMode }` and the segment's offset falls inside
+       * an attached `RevisionRecord.anchor` range in
+       * `document.review.revisions`. Consumers (pm-state-from-snapshot,
+       * render decorations) read these flags as the authoritative
+       * revision-display source of truth — no consumer should compute
+       * its own tracked-change posture from raw revisions.
+       *
+       * Shape mirrors `src/runtime/formatting/formatting-types.ts ::
+       * RevisionDisplayFlags`. Shape is duplicated here (not imported)
+       * because this is the public-types surface; the structural identity
+       * is enforced by `test/runtime/formatting/production-boundary.test.ts`.
+       */
+      revisionDisplay?: {
+        markupMode: "clean" | "simple" | "all";
+        hidden?: boolean;
+        strikethrough?: boolean;
+        insertionUnderline?: boolean;
+        deemphasize?: boolean;
+        authorColor?: string;
+      };
     }
   | {
       segmentId: string;
@@ -1248,7 +1313,7 @@ export type SurfaceBlockSnapshot =
        * this to claim the original block's position span without rendering
        * content.
        *
-       * See docs/plans/lane-2-render-performance.md.
+       * See CLAUDE.md (lane status table)
        */
       placeholderSize?: number;
       state: "locked-preserve-only" | "placeholder-culled";
@@ -1273,7 +1338,7 @@ export interface EditorSurfaceSnapshot {
    * original position range but no content. `null` (default) = all blocks
    * are real (legacy behavior).
    *
-   * See docs/plans/lane-2-render-performance.md.
+   * See CLAUDE.md (lane status table)
    */
   viewportBlockRange: { start: number; end: number } | null;
 }
@@ -2062,22 +2127,15 @@ export interface RuntimeRenderSnapshot {
   grabbedObjectId?: string | null;
 }
 
-export interface EditorSessionState {
-  sessionVersion: "editor-session-state/1";
-  schemaVersion: RuntimePersistedEditorSnapshot["schemaVersion"];
-  documentId: string;
-  docId: string;
-  createdAt: string;
-  updatedAt: string;
-  editorBuild: string;
-  canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
-  compatibility: CompatibilityReport;
-  warningLog: EditorWarning[];
-  protectionSnapshot?: ProtectionSnapshot;
-  sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
-  workflowOverlay?: WorkflowOverlay;
-  workflowMetadata?: WorkflowMetadataSnapshot;
-}
+/**
+ * Back-compat re-export. The canonical definition lives in
+ * `src/session/session-state.ts` (Layer 01 owns the session-state
+ * contract per docs/architecture/01-package-session.md). Kept here so
+ * existing consumers that import `EditorSessionState` from the public
+ * types barrel continue to compile.
+ */
+import type { EditorSessionState } from "../session/session-state.ts";
+export type { EditorSessionState };
 
 export interface PersistedEditorSnapshot {
   snapshotVersion: RuntimePersistedEditorSnapshot["snapshotVersion"];
@@ -2095,6 +2153,10 @@ export interface PersistedEditorSnapshot {
   sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
   workflowOverlay?: WorkflowOverlay;
   workflowMetadata?: WorkflowMetadataSnapshot;
+  /** W10 — class-A overlay-visibility policies (see `OverlayVisibilityPolicy`). */
+  visibilityPolicies?: readonly OverlayVisibilityPolicy[];
+  /** X5 — class-A markup-mode policy (see `WorkflowMarkupModePolicy`). */
+  markupModePolicy?: WorkflowMarkupModePolicy;
 }
 
 export interface AddCommentParams {
@@ -2299,6 +2361,85 @@ export interface WorkflowOverlay {
   metadataPersistence?: MetadataPersistenceMode;
 }
 
+// ---------------------------------------------------------------------------
+// W10 · Overlay-visibility policy (class-A canonical state)
+//
+// Spec: `docs/architecture/06-workflow-review.md` §W10 +
+// `docs/plans/refactor/state-classes-cross-cutting.md` §X1. Layer 06 owns
+// the storage + serialization; Layer 10 composes with the class-C local
+// preference in a single composition site (`ui.overlays.getVisibility`).
+// Consumers should read through `handle.workflow.getVisibilityPolicy(kind)`
+// rather than the overlay store directly.
+// ---------------------------------------------------------------------------
+
+/** Closed union of overlay kinds whose visibility is policy-gated. */
+export type OverlayKind =
+  | "scope-rail"
+  | "comments"
+  | "tracked-changes"
+  | "suggestions"
+  | "debug-panel"
+  | "presence";
+
+/**
+ * Enforcement mode. `"authored-default"` defers to the user's local
+ * preference (class C); `"always"` / `"never"` are hard overrides.
+ */
+export type OverlayVisibilityEnforcement =
+  | "authored-default"
+  | "always"
+  | "never";
+
+/** Audit stamp for a policy change. */
+export interface OverlayVisibilityAuthorship {
+  readonly actorId: string;
+  readonly at: string;
+}
+
+/** Class-A visibility policy for a single overlay kind. */
+export interface OverlayVisibilityPolicy {
+  readonly kind: OverlayKind;
+  readonly enforcement: OverlayVisibilityEnforcement;
+  /** Only consulted when `enforcement === "authored-default"`. */
+  readonly defaultOn: boolean;
+  readonly authoredBy?: OverlayVisibilityAuthorship;
+}
+
+// ---------------------------------------------------------------------------
+// X5 · Workflow markup-mode policy (class-A canonical state)
+//
+// Spec: `docs/plans/refactor/state-classes-cross-cutting.md` §"Slice X5 ·
+// markup-mode retrofit". Parallels the OverlayVisibilityPolicy shape but
+// is single-value (not per-kind) since there is exactly one active markup
+// mode at a time. Composed with the class-C local preference in L10
+// (`ui.viewport.getEffectiveMarkupMode`).
+//
+// Values mirror the existing `revisionMarkupMode` in
+// `src/runtime/formatting/formatting-context.ts` — `"clean" | "simple" |
+// "all"` — so the composed value flows straight into
+// `applyRevisionDisplay(run, revision, markupMode)` without conversion.
+// ---------------------------------------------------------------------------
+
+export type WorkflowMarkupMode = "clean" | "simple" | "all";
+
+/**
+ * Policy enforcement. `"authored-default"` defers to the user's local
+ * preference (class C); `"always"` hard-locks to the authored mode.
+ *
+ * Note: unlike `OverlayVisibilityEnforcement` there is no `"never"`
+ * variant — a markup mode is always one of the three values; "never"
+ * would be non-sensical ("never be in any markup mode" — no value to
+ * pick). The two-value enforcement is sufficient.
+ */
+export type WorkflowMarkupModeEnforcement = "authored-default" | "always";
+
+/** Class-A markup-mode policy. Single record per document. */
+export interface WorkflowMarkupModePolicy {
+  readonly mode: WorkflowMarkupMode;
+  readonly enforcement: WorkflowMarkupModeEnforcement;
+  readonly authoredBy?: OverlayVisibilityAuthorship;
+}
+
 export type WorkflowMetadataPersistence =
   | "runtime-only"
   | "session"
@@ -3452,6 +3593,86 @@ export interface ChartPreviewResolveParams {
   heightEmu: number;
 }
 
+/**
+ * P8 Step 7 — opaque reference the host returns after storing an
+ * embedded-document payload to its own storage. Persisted inside
+ * `customXml/item1.xml` under the `bw:embeddings` namespace so the
+ * session can hand it back to `loadEmbeddedDocument` at export time.
+ *
+ * Field stability: additive only; no field is renamed or removed
+ * across minor versions. Hosts should use structural narrowing to
+ * ignore unknown fields.
+ */
+export interface StorageReference {
+  /**
+   * Host-defined identifier for the storage provider (e.g. `"s3"`,
+   * `"railway-blob"`). Opaque to the editor; the session just
+   * round-trips it.
+   */
+  providerId: string;
+  /**
+   * Opaque handle used by the host to look up the payload. The
+   * session never parses this — it reads, stores, and hands it back
+   * unchanged.
+   */
+  handle: string;
+  /**
+   * SHA-256 hex digest of the original embedded-document bytes.
+   * Computed by the session before calling `storeEmbeddedDocument`
+   * so hosts can detect tampering when rehydrating via
+   * `loadEmbeddedDocument`.
+   */
+  sha256: string;
+}
+
+/**
+ * P8 Step 7 — parameters passed to `EditorHostAdapter.storeEmbeddedDocument`
+ * for every `offloadable` embedding the session encounters at load
+ * time. The host extracts the payload to its storage and returns a
+ * `StorageReference` the session persists into the `bw:embeddings`
+ * customXml namespace.
+ *
+ * Field stability: additive only (same rules as
+ * `ChartPreviewResolveParams`).
+ */
+export interface StoreEmbeddedDocParams {
+  /** Stable identifier of the parent document (the one being opened). */
+  parentDocumentId: string;
+  /**
+   * Manifest entry describing the embedded object. Metadata-only —
+   * the bytes ship separately via the `bytes` field so implementations
+   * can stream them without re-reading through the manifest's lazy
+   * `bytes()` accessor.
+   */
+  embedded: EmbeddedDocumentManifestLike;
+  /**
+   * Materialised bytes of the embedded document. Already extracted
+   * from the OPC package; hosts do not need to call `embedded.bytes()`.
+   */
+  bytes: Uint8Array;
+}
+
+/**
+ * P8 Step 7 — structural subset of `EmbeddedDocumentManifest` (from
+ * `src/session/types.ts`) exposed through the public host-adapter
+ * surface. Avoids forcing the session-layer `EmbeddedDocumentManifest`
+ * symbol to be re-exported from `public-types.ts` while still giving
+ * hosts the metadata fields they need to drive the offload path.
+ *
+ * Field stability: additive only.
+ */
+export interface EmbeddedDocumentManifestLike {
+  /** Stable id across open/export (content-fingerprint derived). */
+  readonly id: string;
+  /** Three-way classification from `classifyEmbedding`. */
+  readonly kind: "digestible" | "offloadable" | "store-only";
+  readonly progId?: string;
+  readonly mimeType?: string;
+  readonly filename?: string;
+  readonly size: number;
+  readonly relationshipId: string;
+}
+
 export interface EditorHostAdapter {
   /**
    * Called once at load time to retrieve a previously-saved session
@@ -3492,6 +3713,42 @@ export interface EditorHostAdapter {
    * activates and the error is logged non-fatally.
    */
   renderChartPreview?(params: ChartPreviewResolveParams): Promise<Uint8Array | null>;
+  /**
+   * P8 Step 7 — store an `offloadable` embedded document out of the
+   * parent OPC package and return a `StorageReference` the session
+   * persists into `customXml/item1.xml` under the `bw:embeddings`
+   * namespace. Called exactly once per `offloadable` manifest entry
+   * at load time, AND only when this method is implemented.
+   *
+   * When this method is absent (or when it throws / rejects), the
+   * session falls back to `store-only` semantics for the entry —
+   * bytes stay on the parent package through the opaque-preservation
+   * path, same as today. Round-trip is byte-identical either way.
+   *
+   * `loadEmbeddedDocument` must round-trip any `StorageReference`
+   * this method returns: calling `loadEmbeddedDocument(ref)` must
+   * yield the same bytes (matching `ref.sha256`) the host received
+   * in `params.bytes`.
+   */
+  storeEmbeddedDocument?(params: StoreEmbeddedDocParams): Promise<StorageReference>;
+  /**
+   * P8 Step 7 — rehydrate an `offloadable` embedded document by its
+   * `StorageReference`. Called at export time for every entry the
+   * session previously persisted into the `bw:embeddings` customXml
+   * namespace via `storeEmbeddedDocument`.
+   *
+   * Return `Uint8Array` — the bytes are written back into the OPC
+   * package at the original relationship target.
+   * Return `null` — the session uses the `inlineBytes` fallback it
+   *   persisted alongside the reference at offload time. Round-trip
+   *   is preserved; the host-storage layer is effectively bypassed
+   *   for this specific entry.
+   *
+   * Rejections and thrown exceptions are caught and treated
+   * identically to a `null` return. Export never fails on storage
+   * unavailability (P3 guarantee).
+   */
+  loadEmbeddedDocument?(ref: StorageReference): Promise<Uint8Array | null>;
 }
 
 export interface EditorDatastoreAdapter {
@@ -3508,7 +3765,7 @@ export interface EditorDatastoreAdapter {
 // `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.
+// `CLAUDE.md (lane status table)` § 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
@@ -3900,6 +4157,23 @@ export interface WordReviewEditorDiagnosticsFacet {
 }
 
 export interface WordReviewEditorRef {
+  /**
+   * L07 closure pass — opt into the V3 public API from a consumer holding
+   * this ref. Returns the frozen `ApiV3` surface (`{ runtime, ai }`) bound
+   * to the same `DocumentRuntime` this ref proxies. The result is cached
+   * per-ref, so repeated calls return the same object reference.
+   *
+   * V3 is strictly additive — all existing V1/V2 ref methods remain. This
+   * method exists so the mounted editor's own host code (and Storybook
+   * consumers, and the probe script) can route through V3 without
+   * standing up a second runtime. Before this method shipped, the only
+   * production `createApiV3()` consumer was `services/debug/` plus test
+   * scripts; this lands V3 as a real production-consumable seam at the
+   * ref boundary.
+   *
+   * See `docs/architecture/07-runtime-api.md` §Seam-reality disclosure.
+   */
+  getApiV3(): ApiV3;
   focus(): void;
   blur(): void;
   undo(): void;
@@ -4006,6 +4280,34 @@ export interface WordReviewEditorRef {
   isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
   getStyleCatalog(): StyleCatalogSnapshot;
+  /**
+   * Replace text at an anchor (or the current selection when omitted).
+   *
+   * **Deprecated for agent / API consumers (refactor/08 Slice-7 plan
+   * §"Retire legacy paths"):** this raw-anchor shape bypasses the
+   * Layer-08 scope compiler's replacement lifecycle (validate →
+   * compile → apply → audit). Agents + platform workblocks must use
+   * the scope-scoped path:
+   *
+   *   - `api.ai.applyReplacementScope({targetScopeId, proposedText})`
+   *     — AI-action-policy + telemetry-audit-backed path.
+   *   - `api.runtime.content.replaceText({scopeId, replacement})` —
+   *     host/UI path without the AI-action-policy composer.
+   *
+   * This ref method stays for UI consumers that dispatch replacements
+   * by live selection position (not by scope id). It emits no
+   * `ScopeActionAudit`; agent paths that call it silently bypass the
+   * audit invariant (S5).
+   *
+   * CI guard: `scripts/ci-check-no-raw-offset-replacetext-on-v3.mjs`
+   * rejects any raw-anchor `replaceText(text, anchor)` shape from the
+   * `src/api/v3/**` surface.
+   *
+   * @deprecated for agent/API callers — use {@link api.ai.applyReplacementScope}
+   *   or {@link api.runtime.content.replaceText} (scope-scoped shapes). Ref
+   *   retained for live-selection UI drivers only.
+   * @see api.ai.applyReplacementScope
+   */
   replaceText(
     text: string,
     target?: EditorAnchorProjection,
@@ -4196,6 +4498,56 @@ export interface WordReviewEditorRef {
   setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /**
+   * W10 — read the class-A overlay-visibility policy for a single
+   * overlay kind. Returns `null` when the document has not authored a
+   * policy for that kind (consumers fall back to class-C defaults).
+   * Composition with the class-C local preference lives in Layer 10
+   * (`ui.overlays.getVisibility`); this method is the class-A read only.
+   */
+  getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null;
+  /**
+   * W10 — read the full class-A policy set. Returns an empty array for
+   * documents that predate the schema.
+   */
+  getVisibilityPolicies(): readonly OverlayVisibilityPolicy[];
+  /**
+   * W10 — author a class-A policy. Persists via `customXml/item1.xml`
+   * on next export + broadcasts via CRDT. Returns `true` when the call
+   * actually changed state; callers can use the boolean to dedupe
+   * subscriber wakeups.
+   */
+  setVisibilityPolicy(policy: OverlayVisibilityPolicy): boolean;
+  /**
+   * W10 — clear a class-A policy (document-predating-schema state).
+   * Returns `true` on actual delete, `false` when no policy was set.
+   */
+  clearVisibilityPolicy(kind: OverlayKind): boolean;
+  /**
+   * W10 — subscribe to class-A policy-set changes (any kind). Fires
+   * after a successful `setVisibilityPolicy` / `clearVisibilityPolicy`
+   * call. Returns an unsubscribe function. Consumed by L10 X3's
+   * `ui.overlays.subscribeVisibility` composition so UI subscribers
+   * re-fire when an authoring tool mutates policy mid-session.
+   */
+  subscribeVisibilityPolicy(listener: () => void): () => void;
+  /**
+   * X5 — read the class-A markup-mode policy (single record). Returns
+   * `null` when the document predates the schema. Composition with the
+   * class-C local preference lives in L10 (`ui.viewport.getEffectiveMarkupMode`).
+   */
+  getMarkupModePolicy(): WorkflowMarkupModePolicy | null;
+  /**
+   * X5 — author the class-A markup-mode policy, or clear with `null`.
+   * Persists via `customXml/item1.xml` on next export + broadcasts via
+   * CRDT when collab is attached. Returns `true` when state changed.
+   */
+  setMarkupModePolicy(policy: WorkflowMarkupModePolicy | null): boolean;
+  /**
+   * X5 — subscribe to markup-mode policy changes. Returns unsubscribe.
+   * Consumed by L10's X5 composition site.
+   */
+  subscribeMarkupModePolicy(listener: () => void): () => void;
   /**
    * Phase C §C1 — filter + project the current workflow overlay into a
    * scope-joined view. Reads a snapshot of the current overlay + metadata
@@ -4902,8 +5254,59 @@ export interface WordReviewEditorProps {
   customSelectionTools?: ReadonlyArray<
     import("../ui/headless/chrome-registry").SelectionToolRegistryEntry
   >;
+  /**
+   * Phase C.γ host-callback bag. When supplied, the workspace mounts
+   * `TwWorkspaceChromeHost` which in turn mounts the right-click
+   * context menu (`TwContextMenuPortal`) and the Ctrl/Cmd+K command
+   * palette (`TwCommandPaletteMount`), dispatching through the shared
+   * `editorActionRegistry`. Actions without a wired callback are
+   * hidden from every surface — progressive disclosure per
+   * `designsystem.md §2.1 principle 4`.
+   *
+   * Omit to preserve pre-Phase-C behavior (no right-click menu, no
+   * palette). Required for the default editor to expose the
+   * Phase C.γ surfaces shipped in `5fce913a`.
+   */
+  editorActionHost?: import("../ui-tailwind/chrome/editor-action-registry").EditorActionHostCallbacks;
+  /**
+   * Forward ref for the workspace's chrome controller. Wires the
+   * `pm-command-bridge` `onContextMenuRequested` callback so a native
+   * `contextmenu` event opens the menu at the click coordinates. Also
+   * consumed by Phase D's inline "More…" buttons on demoted floating
+   * toolbars.
+   */
+  chromeControllerRef?: import("react").Ref<
+    import("../ui-tailwind/chrome/tw-workspace-chrome-host").TwWorkspaceChromeHostController
+  >;
+  /**
+   * Suppress the global Ctrl/Cmd+K palette listener — e.g. when a
+   * higher-priority modal captures keyboard focus. Defaults to
+   * `false` (palette listener is active when `editorActionHost` is
+   * supplied).
+   */
+  commandPaletteDisabled?: boolean;
+  /**
+   * Phase Q runtime-embedded debug UX (refactor/11 Slice 7 + refactor/10
+   * Slice 5).  Default is `"off"` — the editor mounts no debug chrome
+   * and silently ignores the `ui.debug.attach()` hook.  Flip to
+   * `"top-bar"` to mount a slim status bar showing the active session
+   * + scope telemetry, or to `"full"` to mount the tabbed overlay with
+   * inspector / events / REPL panes.
+   *
+   * **CLAUDE.md Protected Invariant** — the default MUST be `"off"`.
+   * Predecessor debug-preview props (`showUnsupportedObjectPreviews`,
+   * `unsupportedPreviewsPolicy`) have regressed their safe defaults
+   * multiple times; keep this one strict.
+   */
+  debugMode?: DebugMode;
 }
 
+/**
+ * Phase Q debug-UX visibility mode.  Consumed by
+ * `WordReviewEditorProps.debugMode` + `src/ui-tailwind/debug/**`.
+ */
+export type DebugMode = "off" | "top-bar" | "full";
+
 /**
  * Selection context handed to host-delegated shortcut callbacks
  * (`onFindRequested`, `onReplaceRequested`, `onGoToRequested`,