@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/api/v3/runtime/geometry.ts

@@ -0,0 +1,349 @@
+/**
+ * @endStateApi v3 — `runtime.geometry` family.
+ *
+ * Reads through `runtime.geometry` — the real Layer-05 `GeometryFacet`
+ * constructed by `src/runtime/document-runtime.ts`. Prior to the
+ * refactor/05 adversarial-closure pass this family adapted geometry
+ * through `runtime.layout` (`layout.getAnchorRects({kind:"block-id", ...})`
+ * + `layout.hitTest`), which named the layer correctly but kept the
+ * real seam in the layout facet. The current wiring reads the facet
+ * directly, so `runtime.geometry.*` is actually geometry-native rather
+ * than geometry-in-name-only.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { mockPayload } from "../_mocks.ts";
+import type { MockPayload } from "../_layer-metadata.ts";
+
+export interface BlockRectEntry {
+  readonly blockId: string;
+  readonly rects: ReadonlyArray<{ x: number; y: number; width: number; height: number; pageIndex?: number }>;
+  readonly alignmentKey?: string;
+  readonly __mock?: true;
+}
+
+export const getBlockRectsMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getBlockRects",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-05-adversarial-closure",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "documentId",
+    shapeDescription:
+      "BlockRectEntry[] with empty rects and a synthetic alignmentKey — emitted when the GeometryFacet is absent (headless tests, pre-paint). Live path walks `runtime.geometry.getBlockRects(blockId)`, which projects the render kernel's current frame through `getBlockRectsFromFrame`; BlockRectEntry.rects is populated per page the block spans with a stable alignmentKey.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "geometry-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getBlockRects. Adapter wraps `GeometryFacet.getBlockRects(blockId)` into BlockRectEntry.rects[]. Promotes to `live` when the v3 shape carries per-page indices (render-kernel per-run anchors slice adds pageIndex to GeometryRect).",
+};
+
+export interface HitTestInput {
+  readonly x: number;
+  readonly y: number;
+  readonly pageIndex?: number;
+}
+
+export interface HitTestResult {
+  readonly blockId?: string;
+  readonly __mock?: true;
+}
+
+/* ================================================================== */
+/*  getCaret — Slice-4 caret geometry (Slice X3 of §4 of coord-05)    */
+/* ================================================================== */
+
+/**
+ * v3 projection of `CaretGeometry` from `src/runtime/geometry/geometry-types.ts`.
+ * Carries the caret rect + baseline + height + writing direction, rebased
+ * into the v3 `{x, y, width, height}` surface convention (no `space`
+ * discriminator — Layer-05 caret reads always return `space: "frame"`).
+ */
+export interface V3CaretGeometry {
+  readonly rect: { readonly x: number; readonly y: number; readonly width: number; readonly height: number };
+  readonly baseline: number;
+  readonly height: number;
+  readonly direction: "ltr" | "rtl";
+}
+
+export const getCaretMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getCaret",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-coord-05-geometry-promotions",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "null when the GeometryFacet is absent (headless pre-paint) or the offset does not resolve. Live path walks `runtime.geometry.getCaret(offset, story)` which composes per-line box + baseline metrics into a CaretGeometry projection.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "selection", auditCategory: "geometry-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getCaret. Adapter wraps GeometryFacet.getCaret(offset, story) → V3CaretGeometry. Substrate caveat (coord-05 §1): single-union-rect for bidi-mixed runs; per-run splitting lands in a later L05 slice.",
+};
+
+/* ================================================================== */
+/*  getSelectionRects                                                  */
+/* ================================================================== */
+
+export interface SelectionRectsInput {
+  readonly from: number;
+  readonly to: number;
+  readonly story?: import("../../public-types.ts").EditorStoryTarget;
+}
+
+export type V3GeometryRect = { readonly x: number; readonly y: number; readonly width: number; readonly height: number };
+
+export const getSelectionRectsMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getSelectionRects",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-coord-05-geometry-promotions",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Empty array when the GeometryFacet is absent or the range doesn't resolve. Live path walks `runtime.geometry.getSelectionRects({from, to, story})` and returns a per-line rect sequence.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "selection", auditCategory: "geometry-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getSelectionRects. Adapter wraps GeometryFacet.getSelectionRects({from, to, story}) → V3GeometryRect[]. Substrate caveat (coord-05 §1): single-union-rect for non-collapsed ranges until per-run anchors land.",
+};
+
+/* ================================================================== */
+/*  getReplacementEnvelope                                             */
+/* ================================================================== */
+
+export interface V3EnvelopeBundle {
+  readonly scopeRects: readonly V3GeometryRect[];
+  readonly attachPoint: { readonly x: number; readonly y: number };
+  readonly confidence: "exact" | "medium" | "detached";
+  readonly linesCrossed: number;
+}
+
+export const getReplacementEnvelopeMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getReplacementEnvelope",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-coord-05-geometry-promotions",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "null when the GeometryFacet is absent or the scopeId doesn't resolve. Live path walks `runtime.geometry.getReplacementEnvelope(scopeId)` returning EnvelopeBundle with scopeRects + attachPoint + confidence.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "geometry-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getReplacementEnvelope. Adapter wraps GeometryFacet.getReplacementEnvelope(scopeId) → V3EnvelopeBundle. Substrate shipped fully — scopeRects is one union rect under today's per-range kernel.",
+};
+
+/* ================================================================== */
+/*  getObjectHandles                                                   */
+/* ================================================================== */
+
+export const getObjectHandlesMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getObjectHandles",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-coord-05-geometry-promotions",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Empty array when the GeometryFacet is absent or the objectId doesn't resolve. Live path walks `runtime.geometry.getObjectHandles(objectId)` returning handle rects.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "geometry-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getObjectHandles. Adapter wraps GeometryFacet.getObjectHandles(objectId) → V3GeometryRect[]. Substrate caveat (coord-05 §1): addresses objects by blockId until the object-specific anchor index ships in a later L05 slice.",
+};
+
+export const hitTestMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.hitTest",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-05-adversarial-closure",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription: "Empty HitTestResult when the GeometryFacet is unwired or the render kernel has not produced a frame (headless tests, pre-paint).",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "hit-test" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.hitTest. Adapter wraps `GeometryFacet.hitTest({xPx,yPx,space:'frame'})` into the v3 HitTestResult shape. Promotes to `live` when the v3 shape matches HitTestResult 1:1.",
+};
+
+export function createGeometryFamily(runtime: RuntimeApiHandle) {
+  // Layer 05 seam. v3's geometry family reads through the real geometry
+  // facet — not through `runtime.layout`. When `runtime.geometry` is
+  // absent (headless harness shims, pre-paint, unwired kernel) each
+  // function falls back to the mock shape so consumers keep a stable
+  // contract.
+  const geometry = runtime.geometry;
+
+  return {
+    getBlockRects(blockIds: readonly string[]): ReadonlyArray<BlockRectEntry & Partial<MockPayload>> {
+      // @endStateApi — live-with-adapter. Routes directly through the
+      // Layer-05 GeometryFacet's `getBlockRects(blockId)`, which walks
+      // the render-kernel frame (`getBlockRectsFromFrame`). When the
+      // facet is absent (no runtime.geometry) or the kernel has not
+      // produced a frame, each entry falls back to the mock shape with
+      // the stable alignmentKey so consumers can still seed rwd seam-4
+      // comparisons.
+      const out: Array<BlockRectEntry & Partial<MockPayload>> = [];
+      for (const blockId of blockIds) {
+        const alignmentKey = `block::${blockId}`;
+        if (!geometry) {
+          out.push(
+            mockPayload(
+              "runtime.geometry unavailable; geometry-facet getBlockRects falls back to synthetic alignmentKey",
+              "BlockRectEntry",
+              { blockId, rects: [], alignmentKey },
+            ),
+          );
+          continue;
+        }
+        const raw = geometry.getBlockRects(blockId);
+        if (raw.length === 0) {
+          // No rects from the facet — the kernel has no frame yet, or
+          // the block is not in the current projection. Emit the mock
+          // shape so downstream consumers can still key on alignmentKey.
+          out.push(
+            mockPayload(
+              "geometry-facet returned no rects for blockId (pre-paint or unknown block)",
+              "BlockRectEntry",
+              { blockId, rects: [], alignmentKey },
+            ),
+          );
+          continue;
+        }
+        const rects = raw.map((r) => ({
+          x: r.leftPx,
+          y: r.topPx,
+          width: r.widthPx,
+          height: r.heightPx,
+        }));
+        out.push({ blockId, rects, alignmentKey });
+      }
+      return out;
+    },
+
+    getCaret(offset: number, story?: import("../../public-types.ts").EditorStoryTarget): V3CaretGeometry | null {
+      // @endStateApi — live-with-adapter. Reads through the GeometryFacet.
+      // Rebases the {leftPx,topPx,widthPx,heightPx,space} shape into the
+      // v3 `{x,y,width,height}` convention (drops the `space` field —
+      // Layer-05 caret reads always resolve to `space: "frame"`).
+      if (!geometry) return null;
+      const raw = geometry.getCaret(offset, story);
+      if (!raw) return null;
+      return {
+        rect: { x: raw.rect.leftPx, y: raw.rect.topPx, width: raw.rect.widthPx, height: raw.rect.heightPx },
+        baseline: raw.baseline,
+        height: raw.height,
+        direction: raw.direction,
+      };
+    },
+
+    getSelectionRects(input: SelectionRectsInput): readonly V3GeometryRect[] {
+      // @endStateApi — live-with-adapter. Reads through GeometryFacet.
+      // Returns an empty array when the facet is absent or the range
+      // does not resolve; callers can distinguish no-resolution from
+      // collapsed-range by checking `from === to`.
+      if (!geometry) return [];
+      const rects = geometry.getSelectionRects({ from: input.from, to: input.to, story: input.story });
+      return rects.map((r) => ({ x: r.leftPx, y: r.topPx, width: r.widthPx, height: r.heightPx }));
+    },
+
+    getReplacementEnvelope(scopeId: string): V3EnvelopeBundle | null {
+      // @endStateApi — live-with-adapter. Reads through GeometryFacet.
+      // Rebases scopeRects into the v3 {x,y,width,height} convention;
+      // attachPoint drops `space` since Layer-05 produces frame-space
+      // coordinates.
+      if (!geometry) return null;
+      const raw = geometry.getReplacementEnvelope(scopeId);
+      if (!raw) return null;
+      return {
+        scopeRects: raw.scopeRects.map((r) => ({ x: r.leftPx, y: r.topPx, width: r.widthPx, height: r.heightPx })),
+        attachPoint: { x: raw.attachPoint.xPx, y: raw.attachPoint.yPx },
+        confidence: raw.confidence,
+        linesCrossed: raw.linesCrossed,
+      };
+    },
+
+    getObjectHandles(objectId: string): readonly V3GeometryRect[] {
+      // @endStateApi — live-with-adapter. Reads through GeometryFacet.
+      // Substrate addresses objects by blockId via
+      // frame.anchorIndex.byBlockId — see metadata.rwdReference for the
+      // caveat.
+      if (!geometry) return [];
+      const rects = geometry.getObjectHandles(objectId);
+      return rects.map((r) => ({ x: r.leftPx, y: r.topPx, width: r.widthPx, height: r.heightPx }));
+    },
+
+    hitTest(input: HitTestInput): HitTestResult & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Reads through the GeometryFacet
+      // so the v3 seam matches the runtime seam. The facet routes the
+      // point through `resolveHitTest` against the render kernel's
+      // current frame (Slice 2a); `space: "frame"` is the only coordinate
+      // space the kernel emits today (G5).
+      if (!geometry) {
+        return mockPayload(
+          "runtime.geometry unavailable",
+          "HitTestResult",
+          {} as { blockId?: string },
+        );
+      }
+      const result = geometry.hitTest({ xPx: input.x, yPx: input.y, space: "frame" });
+      if (!result) {
+        return mockPayload(
+          "geometry-facet hitTest returned null (out-of-frame point or no frame)",
+          "HitTestResult",
+          {} as { blockId?: string },
+        );
+      }
+      return { blockId: result.blockId };
+    },
+  };
+}

package/src/api/v3/runtime/layout.ts

@@ -0,0 +1,108 @@
+/**
+ * @endStateApi v3 — `runtime.layout` family.
+ *
+ * getPage (live-with-adapter) / getPageSpan (live-with-adapter) /
+ * getBlockLayout (live-with-adapter). Adapter delegation to the existing
+ * layout facet (`runtime.layout`).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata, MockPayload } from "../_layer-metadata.ts";
+import { mockPayload } from "../_mocks.ts";
+
+export const getPageMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getPage",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "phase-p-prime",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "layout-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getPage. Adapter wraps facet.getPage(pageIndex) to expose the v3-shaped PageNode; promotes to `live` when the v3 shape matches PublicPageNode 1:1.",
+};
+
+export const getPageSpanMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getPageSpan",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "phase-p-prime",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription: "Fallback PageSpan when the block has no measurement entry (pre-layout or unknown blockId); pageIndex=null, __mock:true.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "layout-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getPageSpan. Adapter composes facet.getMeasurement(blockId) into a {blockId, pageIndex} shape; promotes to `live` when the facet exposes getPageSpanForBlock directly.",
+};
+
+export const getBlockLayoutMetadata: ApiV3FnMetadata = {
+  name: "runtime.layout.getBlockLayout",
+  status: "live-with-adapter",
+  sourceLayer: "layout-semantics",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "phase-p-prime",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "layout-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.layout.getBlockLayout. Adapter wraps facet.getMeasurement(blockId) → PublicBlockMeasurement; promotes to `live` when the v3 shape matches 1:1.",
+};
+
+export function createLayoutFamily(runtime: RuntimeApiHandle) {
+  // Public-facet shape — see src/runtime/layout/public-facet.ts:376+.
+  const layout = runtime.layout;
+
+  return {
+    getPage(pageIndex: number) {
+      // @endStateApi — live-with-adapter. Wraps the facet's
+      // getPage(pageIndex); promotes to `live` when the v3 shape matches
+      // PublicPageNode 1:1.
+      return layout?.getPage(pageIndex) ?? null;
+    },
+
+    getPageSpan(blockId: string): unknown | (unknown & MockPayload) {
+      // @endStateApi — live-with-adapter. The facet exposes no direct
+      // "span for block" read. Adapter composes getMeasurement(blockId)
+      // into {blockId, pageIndex}; returns a mock-flagged fallback when
+      // the measurement provider has not observed the block.
+      const measurement = layout?.getMeasurement(blockId) as
+        | { pageIndex?: number }
+        | null
+        | undefined;
+      if (!measurement) {
+        return mockPayload(
+          "layout facet has no getPageSpanForBlock; Phase 2 formalization needed",
+          "PageSpan",
+          { blockId, pageIndex: null as number | null },
+        );
+      }
+      return {
+        blockId,
+        pageIndex: measurement.pageIndex ?? null,
+      };
+    },
+
+    getBlockLayout(blockId: string) {
+      // @endStateApi — live-with-adapter. Wraps
+      // layout.getMeasurement(blockId) → PublicBlockMeasurement; promotes
+      // to `live` when the v3 shape matches 1:1.
+      return layout?.getMeasurement(blockId) ?? null;
+    },
+  };
+}

package/src/api/v3/runtime/review.ts

@@ -0,0 +1,129 @@
+/**
+ * @endStateApi v3 — `runtime.review` family.
+ *
+ * getComments (live) / getChanges (live) / acceptChange (live) /
+ * resolveComment (live).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  CommentSidebarThreadSnapshot,
+  TrackedChangeEntrySnapshot,
+} from "../../public-types.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+
+export const getCommentsMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.getComments",
+  status: "live",
+  sourceLayer: "workflow-review",
+  // Concrete, reviewable proof: L06 Slice-4F graduated this function to
+  // `live` by routing through `runtime.getRenderSnapshot().comments.threads`.
+  // The `review-full-snapshot` test covers F09 (non-empty comments) + F11
+  // (non-empty revisions) + the F01 empty-case negative test; L07 closure
+  // pass added behavioral-coverage + mutation-behavioral assertions.
+  // Reviewers can open the cited files to see the asserts.
+  liveEvidence: {
+    runnerTest:
+      "test/api/v3/review-full-snapshot.test.ts,test/api/v3/live-parity.test.ts,test/api/v3/behavioral-coverage.test.ts,test/api/v3/review-mutation-behavioral.test.ts",
+    commit: "refactor-06-slice-4f-2026-04-22",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "review-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§Runtime API § runtime.review.getComments",
+};
+
+export const getChangesMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.getChanges",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest:
+      "test/api/v3/review-full-snapshot.test.ts,test/api/v3/live-parity.test.ts,test/api/v3/behavioral-coverage.test.ts,test/api/v3/review-mutation-behavioral.test.ts",
+    commit: "refactor-06-slice-4f-2026-04-22",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "review-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§Runtime API § runtime.review.getChanges",
+};
+
+export const acceptChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.acceptChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    // Direct mutation + UxResponse proof. The behavioral test asserts
+    // before/after snapshot parity via getReviewWorkSnapshot + one
+    // ux.response event emission per call (R4).
+    runnerTest: "test/api/v3/review-mutation-behavioral.test.ts",
+    commit: "refactor-07-adversarial-closure-2026-04-22",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "change mark disappears and text merges" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "change-accept" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.review.acceptChange",
+};
+
+export const resolveCommentMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.resolveComment",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/review-mutation-behavioral.test.ts",
+    commit: "refactor-07-adversarial-closure-2026-04-22",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "comment thread collapses to resolved" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "comment-resolve" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.review.resolveComment",
+};
+
+export function createReviewFamily(runtime: RuntimeApiHandle) {
+  return {
+    getComments(): readonly CommentSidebarThreadSnapshot[] {
+      // @endStateApi — live. Reads the full comment sidebar snapshot from
+      // the canonical render surface. Layer-06 Slice 3 graduation.
+      return runtime.getRenderSnapshot().comments.threads;
+    },
+
+    getChanges(): readonly TrackedChangeEntrySnapshot[] {
+      // @endStateApi — live. Reads the full tracked-changes revision list
+      // from the canonical render surface. Layer-06 Slice 3 graduation.
+      return runtime.getRenderSnapshot().trackedChanges.revisions;
+    },
+
+    acceptChange(changeId: string): void {
+      // @endStateApi — live. Delegates.
+      runtime.acceptChange(changeId);
+      emitUxResponse(runtime, {
+        apiFn: acceptChangeMetadata.name,
+        intent: acceptChangeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: acceptChangeMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "inline-change", payload: { changeId } },
+      });
+    },
+
+    resolveComment(commentId: string): void {
+      // @endStateApi — live.
+      runtime.resolveComment(commentId);
+      emitUxResponse(runtime, {
+        apiFn: resolveCommentMetadata.name,
+        intent: resolveCommentMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: resolveCommentMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "inline-change", payload: { commentId } },
+      });
+    },
+  };
+}

package/src/api/v3/runtime/search.ts

@@ -0,0 +1,74 @@
+/**
+ * @endStateApi v3 — `runtime.search` family.
+ *
+ * Single function: `searchDocument(...)`. Thin pass-through over the
+ * shipped compound search path `src/runtime/document-search.ts`.
+ *
+ * Distinct from `runtime.content.search(input)` — the content-family
+ * seam is a simple query + optional limit over `findAllText` returning
+ * `EditorAnchorProjection[]`. This family exposes the richer compound
+ * path: it takes the canonical document + selection + active story +
+ * navigation snapshot + options, and returns per-match excerpts with
+ * page/section metadata. Same inputs the PM surface
+ * (`tw-prosemirror-surface.tsx`) already holds — exposing it through v3
+ * lets L11 flip its `src/runtime/document-search.ts` import to the v3
+ * seam (coord-11 §4.3).
+ *
+ * Pure-function read — `stateClass: "C-local"` + `persistsTo: "none"`.
+ * No UxResponse emission.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type {
+  CanonicalDocumentEnvelope,
+  DocumentNavigationSnapshot,
+  EditorStoryTarget,
+  SearchOptions,
+  SearchResultSnapshot,
+  SelectionSnapshot,
+} from "../../public-types.ts";
+import { searchDocument as searchDocumentImpl } from "../../../runtime/document-search.ts";
+
+export const searchDocumentMetadata: ApiV3FnMetadata = {
+  name: "runtime.search.searchDocument",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-search-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "search",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.search.searchDocument. Direct delegation to searchDocument (src/runtime/document-search.ts). Compound search over canonical doc + selection + activeStory + navigation + query + options. Returns SearchResultSnapshot[] with per-match excerpts + page/section metadata. Complements the simpler runtime.content.search.",
+};
+
+export function createSearchFamily(_runtime: RuntimeApiHandle) {
+  return {
+    searchDocument(
+      document: CanonicalDocumentEnvelope,
+      selection: SelectionSnapshot,
+      activeStory: EditorStoryTarget,
+      navigation: DocumentNavigationSnapshot,
+      query: string,
+      options?: SearchOptions,
+    ): SearchResultSnapshot[] {
+      // @endStateApi — live.
+      return searchDocumentImpl(
+        document,
+        selection,
+        activeStory,
+        navigation,
+        query,
+        options,
+      );
+    },
+  };
+}