@beyondwork/docx-react-component 1.0.103 → 1.0.105

package/package.json

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

package/src/api/public-types.ts

@@ -177,9 +177,11 @@ export type {
   PublicBlockMeasurement,
   PublicFieldDirtinessReport,
   PublicLineBox,
+  PublicLayoutDivergence,
   PublicMeasurementFidelity,
   PublicNoteAllocation,
   PublicPageAnchor,
+  PublicPageFrame,
   PublicPageNode,
   PublicPageRegion,
   PublicPageRegions,
@@ -190,6 +192,7 @@ export type {
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
   PublicSectionNode,
+  PublicTwipsRect,
   // R0.5: named page-format + margin-preset catalogs
   PageFormatDefinition,
   ActivePageFormat,
@@ -1223,6 +1226,23 @@ export interface SurfacePictureEffects {
   glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
 }
 
+export interface SurfacePreserveOnlyObjectSizing {
+  sourceId?: string;
+  display: "inline" | "floating" | "unknown";
+  extentEmu?: { widthEmu: number; heightEmu: number };
+  fallbackHint:
+    | "drawing-inline"
+    | "drawing-floating"
+    | "chart"
+    | "smartart"
+    | "shape"
+    | "wordart"
+    | "vml-shape"
+    | "ole-object"
+    | "opaque-object";
+  relationshipIds?: string[];
+}
+
 export type SurfaceInlineSegment =
   | {
       segmentId: string;
@@ -1338,6 +1358,20 @@ export type SurfaceInlineSegment =
        * can render `ChartSurface` instead of the fallback bitmap or badge.
        */
       parsedChartId?: string;
+      /**
+       * PE2 preserve-only object handoff. Present for unsupported drawing,
+       * chart, SmartArt, WordArt, VML, and opaque-object previews when import
+       * could recover source ids, relationship ids, fallback hints, or
+       * extents. Layout consumers may size placeholders from this metadata;
+       * it is not a layout computation.
+       */
+      preserveOnlyObject?: SurfacePreserveOnlyObjectSizing;
+      /**
+       * Drawing anchor geometry for preserve-only objects that originated in a
+       * `drawing_frame`. Mirrors image/shape anchor semantics so L04 can join
+       * the object to source/canonical/layout rows without re-parsing OOXML.
+       */
+      anchor?: SurfaceDrawingAnchor;
       state: "locked-preserve-only";
     }
   | {
@@ -1403,6 +1437,7 @@ export type SurfaceInlineSegment =
       isTextBox?: boolean;
       /** Text box body layout from `wps:bodyPr` / `a:bodyPr`. */
       textBoxBody?: SurfaceTextBoxBodyProperties;
+      preserveOnlyObject?: SurfacePreserveOnlyObjectSizing;
       /** First-paragraph plain-text preview when `isTextBox` is true. */
       txbxText?: string;
       /** Run-level marks from the first text-box text run, when available. */
@@ -3609,6 +3644,11 @@ export interface WordReviewEditorPasteEvent {
   source: "paste" | "drop";
 }
 
+export interface WorkflowEventOrigin {
+  readonly source: "api" | "runtime" | "collab" | string;
+  readonly at?: string;
+}
+
 export type WordReviewEditorEvent =
   | {
       type: "ready";
@@ -3724,16 +3764,38 @@ export type WordReviewEditorEvent =
       type: "workflow_overlay_changed";
       documentId: string;
       snapshot: WorkflowScopeSnapshot;
+      origin?: WorkflowEventOrigin;
     }
   | {
       type: "workflow_active_work_item_changed";
       documentId: string;
       activeWorkItemId: string | null;
+      origin?: WorkflowEventOrigin;
     }
   | {
       type: "workflow_metadata_changed";
       documentId: string;
       snapshot: WorkflowMetadataSnapshot;
+      origin?: WorkflowEventOrigin;
+    }
+  | {
+      type: "workflow_shared_state_changed";
+      documentId: string;
+      state: SharedWorkflowState | null;
+      origin: WorkflowEventOrigin;
+    }
+  | {
+      type: "workflow_visibility_policy_changed";
+      documentId: string;
+      kind?: OverlayKind;
+      policy?: OverlayVisibilityPolicy | null;
+      origin: WorkflowEventOrigin;
+    }
+  | {
+      type: "workflow_markup_mode_policy_changed";
+      documentId: string;
+      policy: WorkflowMarkupModePolicy | null;
+      origin: WorkflowEventOrigin;
     }
   | {
       type: "host_annotation_overlay_changed";
@@ -5010,7 +5072,10 @@ export interface WordReviewEditorRef {
    * `replaceText` calls to block with `workflow_comment_only`.
    */
   getWorkflowOverlay(): WorkflowOverlay | null;
-  setSharedWorkflowState(state: SharedWorkflowState | null): void;
+  setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin?: WorkflowEventOrigin,
+  ): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;

package/src/api/v3/_runtime-handle.ts

@@ -48,6 +48,7 @@ export type RuntimeApiHandle = Pick<
   | "getCompatibilityReport"
   | "getWarnings"
   | "getRenderSnapshot"
+  | "getDocumentNavigationSnapshot"
   // Canonical document read (ai.inspect + ai.bundle + ai.resolve families,
   // added in refactor/08 Slice 2/3 graduations)
   | "getCanonicalDocument"
@@ -155,6 +156,7 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getCompatibilityReport: true,
   getWarnings: true,
   getRenderSnapshot: true,
+  getDocumentNavigationSnapshot: true,
   getCanonicalDocument: true,
   findAllText: true,
   replaceText: true,

package/src/api/v3/ai/_pe2-evidence.ts

@@ -0,0 +1,153 @@
+/**
+ * Layer 09 PE2 evidence projection.
+ *
+ * The AI API should not leak the full runtime geometry index. Agents need a
+ * small, JSON-stable read model that says whether PE2 geometry evidence is
+ * available and, for scope reads, whether a replacement envelope exists for
+ * the requested scope.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type {
+  GeometryIndexCoverage,
+  GeometryPrecision,
+  GeometryRehydrationStatus,
+  GeometryReplacementEnvelopeEntry,
+  GeometrySourceIdentity,
+} from "../../../runtime/geometry/index.ts";
+
+export interface AiPe2GeometryCoverageEvidence {
+  readonly status: GeometryRehydrationStatus;
+  readonly pageCount: number;
+  readonly regionCount: number;
+  readonly sliceCount: number;
+  readonly lineCount: number;
+  readonly anchorCount: number;
+  readonly hitTargetCount: number;
+  readonly semanticEntryCount: number;
+  readonly replacementEnvelopeCount: number;
+  readonly objectHandleCount: number;
+  readonly precision: {
+    readonly exact: number;
+    readonly "within-tolerance": number;
+    readonly heuristic: number;
+  };
+}
+
+export interface AiPe2DocumentEvidence {
+  readonly geometry: AiPe2GeometryCoverageEvidence;
+}
+
+export interface AiPe2ScopeReplacementEnvelopeEvidence {
+  readonly status: GeometryRehydrationStatus;
+  readonly precision: GeometryPrecision;
+  readonly rectCount: number;
+  readonly pageIds?: readonly string[];
+  readonly sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface AiPe2ScopeEvidence {
+  readonly geometry: {
+    readonly coverage: AiPe2GeometryCoverageEvidence;
+    readonly replacementEnvelope?: AiPe2ScopeReplacementEnvelopeEvidence;
+    readonly reason?: "geometry-index-unavailable" | "scope-envelope-not-found";
+  };
+}
+
+function copyCoverage(coverage: GeometryIndexCoverage): AiPe2GeometryCoverageEvidence {
+  return {
+    status: coverage.status,
+    pageCount: coverage.pageCount,
+    regionCount: coverage.regionCount,
+    sliceCount: coverage.sliceCount,
+    lineCount: coverage.lineCount,
+    anchorCount: coverage.anchorCount,
+    hitTargetCount: coverage.hitTargetCount,
+    semanticEntryCount: coverage.semanticEntryCount,
+    replacementEnvelopeCount: coverage.replacementEnvelopeCount,
+    objectHandleCount: coverage.objectHandleCount,
+    precision: {
+      exact: coverage.precision.exact,
+      "within-tolerance": coverage.precision["within-tolerance"],
+      heuristic: coverage.precision.heuristic,
+    },
+  };
+}
+
+function copyEnvelope(
+  envelope: GeometryReplacementEnvelopeEntry,
+): AiPe2ScopeReplacementEnvelopeEvidence {
+  return {
+    status: envelope.status,
+    precision: envelope.precision,
+    rectCount: envelope.rects.length,
+    ...(envelope.pageIds ? { pageIds: [...envelope.pageIds] } : {}),
+    ...(envelope.sourceIdentity ? { sourceIdentity: { ...envelope.sourceIdentity } } : {}),
+  };
+}
+
+const UNAVAILABLE_COVERAGE: AiPe2GeometryCoverageEvidence = {
+  status: "unavailable",
+  pageCount: 0,
+  regionCount: 0,
+  sliceCount: 0,
+  lineCount: 0,
+  anchorCount: 0,
+  hitTargetCount: 0,
+  semanticEntryCount: 0,
+  replacementEnvelopeCount: 0,
+  objectHandleCount: 0,
+  precision: { exact: 0, "within-tolerance": 0, heuristic: 0 },
+};
+
+export function projectDocumentPe2Evidence(
+  runtime: RuntimeApiHandle,
+): AiPe2DocumentEvidence {
+  if (!runtime.geometry) {
+    return { geometry: UNAVAILABLE_COVERAGE };
+  }
+  return {
+    geometry: copyCoverage(runtime.geometry.getGeometryCoverage()),
+  };
+}
+
+export function projectScopePe2Evidence(
+  runtime: RuntimeApiHandle,
+  scopeId: string,
+): AiPe2ScopeEvidence {
+  if (!runtime.geometry) {
+    return {
+      geometry: {
+        coverage: UNAVAILABLE_COVERAGE,
+        reason: "geometry-index-unavailable",
+      },
+    };
+  }
+  const coverage = copyCoverage(runtime.geometry.getGeometryCoverage());
+  const index = runtime.geometry.getGeometryIndex();
+  if (!index) {
+    return {
+      geometry: {
+        coverage,
+        reason: "geometry-index-unavailable",
+      },
+    };
+  }
+
+  const envelope = index.replacementEnvelopes.find((entry) => entry.scopeId === scopeId);
+  if (!envelope) {
+    return {
+      geometry: {
+        coverage,
+        reason: "scope-envelope-not-found",
+      },
+    };
+  }
+
+  return {
+    geometry: {
+      coverage,
+      replacementEnvelope: copyEnvelope(envelope),
+    },
+  };
+}

package/src/api/v3/ai/bundle.ts

@@ -24,6 +24,10 @@ import {
   type SemanticScope,
 } from "../../../runtime/scopes/index.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  projectScopePe2Evidence,
+  type AiPe2ScopeEvidence,
+} from "./_pe2-evidence.ts";
 
 /**
  * Handle-shaped input (architecture A3 — scope-handle-first targeting).
@@ -42,8 +46,9 @@ export interface GetScopeBundleInput {
   readonly nowUtc: string;
 }
 
-/** Re-export the runtime-side `ScopeBundle` so v3 consumers get the rich shape. */
-export type { RuntimeScopeBundle as ScopeBundle };
+export type ScopeBundle = RuntimeScopeBundle & {
+  readonly pe2Evidence: AiPe2ScopeEvidence;
+};
 
 export interface ScopeBundleNotFound {
   readonly notFound: true;
@@ -91,7 +96,7 @@ export const getScopeBundleMetadata: ApiV3FnMetadata = {
     boundedScope: "scope",
     auditCategory: "scope-bundle",
     contextPromptShape:
-      "Bundle content + formatting + layout + geometry + workflow + replaceability for prompt context.",
+      "Bundle content + formatting + layout + geometry + workflow + replaceability + PE2 geometry coverage/envelope evidence for prompt context.",
   },
   stateClass: "A-canonical",
   persistsTo: "canonical",
@@ -110,7 +115,7 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
       return compiled?.scope ?? null;
     },
 
-    getScopeBundle(input: GetScopeBundleInput): RuntimeScopeBundle | ScopeBundleNotFound {
+    getScopeBundle(input: GetScopeBundleInput): ScopeBundle | ScopeBundleNotFound {
       // @endStateApi — live-with-adapter. Routes through the compiler-
       // service facade.
       //
@@ -126,7 +131,10 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
           reason: "no scope with this id in canonical document or review store",
         };
       }
-      return bundle;
+      return {
+        ...bundle,
+        pe2Evidence: projectScopePe2Evidence(runtime, scopeId),
+      };
     },
   };
 }

package/src/api/v3/ai/inspect.ts

@@ -16,6 +16,10 @@ import {
   type SemanticScopeKind,
 } from "../../../runtime/scopes/index.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  projectDocumentPe2Evidence,
+  type AiPe2DocumentEvidence,
+} from "./_pe2-evidence.ts";
 
 export interface InspectDocumentResult {
   readonly documentId: string;
@@ -23,6 +27,7 @@ export interface InspectDocumentResult {
   readonly pageCount?: number;
   readonly semanticSummary: string;
   readonly kindDistribution: Readonly<Partial<Record<SemanticScopeKind, number>>>;
+  readonly pe2Evidence: AiPe2DocumentEvidence;
 }
 
 export const inspectDocumentMetadata: ApiV3FnMetadata = {
@@ -40,7 +45,7 @@ export const inspectDocumentMetadata: ApiV3FnMetadata = {
     boundedScope: "document",
     auditCategory: "document-inspect",
     contextPromptShape:
-      "Summarize document by scope count + page count + semantic kind distribution.",
+      "Summarize document by scope count + page count + semantic kind distribution + PE2 geometry coverage evidence.",
   },
   stateClass: "A-canonical",
   persistsTo: "canonical",
@@ -97,6 +102,7 @@ export function createInspectFamily(runtime: RuntimeApiHandle) {
         scopeCount: scopes.length,
         semanticSummary: summary,
         kindDistribution,
+        pe2Evidence: projectDocumentPe2Evidence(runtime),
       };
     },
 

package/src/api/v3/ai/outline.ts

@@ -19,7 +19,6 @@ import type {
   DocumentOutlineHeadingSnapshot,
   DocumentOutlineSnapshot,
 } from "../../public-types.ts";
-import { createDocumentNavigationSnapshot } from "../../../runtime/document-navigation.ts";
 import { createDocumentOutlineSnapshot } from "../../../runtime/document-outline.ts";
 import {
   computeBlockPositions,
@@ -68,7 +67,7 @@ export const getDocumentOutlineMetadata: ApiV3FnMetadata = {
   stateClass: "A-canonical",
   persistsTo: "canonical",
   rwdReference:
-    "§AI API § ai.getDocumentOutline. Composes createDocumentNavigationSnapshot (L04/07) with createDocumentOutlineSnapshot (L07) to surface the heading tree. Read-only; no audit emission.",
+    "§AI API § ai.getDocumentOutline. Composes runtime.getDocumentNavigationSnapshot() (L04 graph-derived navigation) with createDocumentOutlineSnapshot (L07) to surface the heading tree. Read-only; no audit emission.",
 };
 
 export function createOutlineFamily(runtime: RuntimeApiHandle) {
@@ -82,11 +81,7 @@ export function createOutlineFamily(runtime: RuntimeApiHandle) {
       const snapshot = runtime.getRenderSnapshot();
       const document = runtime.getCanonicalDocument();
       const selectionHead = snapshot.selection.head;
-      const navigation = createDocumentNavigationSnapshot(
-        document,
-        selectionHead,
-        snapshot.activeStory,
-      );
+      const navigation = runtime.getDocumentNavigationSnapshot();
       const outline = createDocumentOutlineSnapshot({
         navigation,
         activeStory: snapshot.activeStory,

package/src/api/v3/ai/replacement.ts

@@ -123,6 +123,7 @@ export interface ApplyResult {
   readonly applied: boolean;
   readonly reason?: string;
   readonly blockers?: readonly string[];
+  readonly blockerDetails?: readonly ActionBlockerDetail[];
   readonly auditHint?: string;
   /**
    * Gap A (post-Slice-7 integration) — revision IDs authored during
@@ -133,6 +134,19 @@ export interface ApplyResult {
   readonly authoredRevisionIds: readonly string[];
 }
 
+export interface ActionBlockerDetail {
+  readonly code: string;
+  readonly category:
+    | "unsupported-scope-kind"
+    | "unsupported-operation"
+    | "unresolved-scope"
+    | "policy-or-guard";
+  readonly message: string;
+  readonly nextStep: string;
+  readonly scopeKind?: string;
+  readonly operation?: string;
+}
+
 export interface ApplyReplacementScopeInput {
   readonly targetScopeId: string;
   readonly operation?: ReplacementOperationKind;
@@ -263,6 +277,97 @@ function projectValidationResult(
   };
 }
 
+function blockerDetailFor(code: string): ActionBlockerDetail | null {
+  if (code.startsWith("scope-not-resolvable:")) {
+    return {
+      code,
+      category: "unresolved-scope",
+      message: "The target scope no longer resolves in the current document.",
+      nextStep:
+        "Call ai.resolveReference or ai.queryScopeAtPosition again, then retry with the returned handle's scopeId.",
+    };
+  }
+
+  if (!code.startsWith("compile-refused:")) return null;
+
+  const [, scopeKind = "unknown", ...rest] = code.split(":");
+  const suffix = rest.join(":");
+  if (suffix.startsWith("operation-not-implemented:")) {
+    const operation = suffix.slice("operation-not-implemented:".length);
+    return {
+      code,
+      category: "unsupported-operation",
+      scopeKind,
+      operation,
+      message: `The ${operation} operation is not implemented for ${scopeKind} scopes.`,
+      nextStep:
+        "Retry with operation:\"replace\" when that is acceptable, or attach an explanation/issue instead of mutating.",
+    };
+  }
+
+  if (scopeKind === "scope" && suffix === "multi-paragraph-replace-not-implemented") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: "Multi-paragraph scope replacement is not implemented.",
+      nextStep:
+        "Split the request into paragraph-scoped replacements, or attach an explanation/issue until the multi-paragraph planner ships.",
+    };
+  }
+
+  if (scopeKind === "table" || scopeKind === "table-row" || scopeKind === "table-cell") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: `Flat text replacement is not implemented for ${scopeKind} scopes because it can break table structure.`,
+      nextStep:
+        "Use ai.attachExplanation or ai.createIssue for now, or wait for the Layer 08 table-family replacement planner.",
+    };
+  }
+
+  if (scopeKind === "field") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: "Field result replacement is preserve-only because field text is computed from instructions.",
+      nextStep:
+        "Attach an explanation/issue, or use a future field-aware edit path that updates field instructions safely.",
+    };
+  }
+
+  if (scopeKind === "image" || scopeKind === "note") {
+    return {
+      code,
+      category: "unsupported-scope-kind",
+      scopeKind,
+      message: `Replacement is not implemented for ${scopeKind} scopes.`,
+      nextStep:
+        "Attach an explanation/issue rather than mutating until a scope-specific planner exists.",
+    };
+  }
+
+  return {
+    code,
+    category: "unsupported-scope-kind",
+    scopeKind,
+    message: `Replacement is not implemented for ${scopeKind} scopes.`,
+    nextStep:
+      "Use a supported paragraph-like scope, or attach an explanation/issue and route the unsupported planner to the owning layer.",
+  };
+}
+
+function projectBlockerDetails(
+  blockers: readonly string[],
+): readonly ActionBlockerDetail[] | undefined {
+  const details = blockers
+    .map((code) => blockerDetailFor(code))
+    .filter((detail): detail is ActionBlockerDetail => detail !== null);
+  return details.length > 0 ? Object.freeze(details) : undefined;
+}
+
 export function createReplacementFamily(runtime: RuntimeApiHandle) {
   const compiler = createScopeCompilerService(runtime);
   return {
@@ -371,6 +476,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         expectedDelta: applyReplacementScopeMetadata.uxIntent.expectedDelta,
       });
 
+      const blockerDetails = projectBlockerDetails(
+        result.validation.blockedReasons,
+      );
       return {
         proposalId,
         applied: result.applied,
@@ -378,6 +486,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
+        ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };
@@ -412,6 +521,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         expectedDelta: applyScopeActionMetadata.uxIntent.expectedDelta,
       });
 
+      const blockerDetails = projectBlockerDetails(
+        result.validation.blockedReasons,
+      );
       return {
         proposalId,
         applied: result.applied,
@@ -419,6 +531,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
+        ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };

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

@@ -15,6 +15,26 @@ 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";
+import type {
+  GeometryIndex,
+  GeometryIndexCoverage,
+} from "../../../runtime/geometry/index.ts";
+
+function createUnavailableGeometryCoverage(): GeometryIndexCoverage {
+  return {
+    status: "unavailable",
+    pageCount: 0,
+    regionCount: 0,
+    sliceCount: 0,
+    lineCount: 0,
+    anchorCount: 0,
+    hitTargetCount: 0,
+    semanticEntryCount: 0,
+    replacementEnvelopeCount: 0,
+    objectHandleCount: 0,
+    precision: { exact: 0, "within-tolerance": 0, heuristic: 0 },
+  };
+}
 
 export interface BlockRectEntry {
   readonly blockId: string;
@@ -57,6 +77,50 @@ export interface HitTestResult {
   readonly __mock?: true;
 }
 
+/* ================================================================== */
+/*  PE2 geometry index + coverage                                     */
+/* ================================================================== */
+
+export const getGeometryIndexMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getGeometryIndex",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-pe2-geometry-index-read-surface",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "geometry-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getGeometryIndex. PE2 read surface over GeometryFacet.getGeometryIndex(): renderer-neutral pages, regions, slices, lines, anchors, hit targets, semantic entries, replacement envelopes, object handles, and coverage. Returns null when no geometry facet or render frame is warm. Promotes to live when L05 projects directly from L04 page slices instead of the render-frame adapter.",
+};
+
+export const getGeometryCoverageMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getGeometryCoverage",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-pe2-geometry-index-read-surface",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "geometry-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getGeometryCoverage. PE2 lightweight status read over GeometryFacet.getGeometryCoverage(). Always returns a coverage object; unwired/pre-paint states report status:'unavailable' with zero counts so agents and evidence runners can distinguish no geometry from empty geometry.",
+};
+
 /* ================================================================== */
 /*  getCaret — Slice-4 caret geometry (Slice X3 of §4 of coord-05)    */
 /* ================================================================== */
@@ -224,6 +288,21 @@ export function createGeometryFamily(runtime: RuntimeApiHandle) {
   const geometry = runtime.geometry;
 
   return {
+    getGeometryIndex(): GeometryIndex | null {
+      // @endStateApi — live-with-adapter. Exposes the Layer-05 PE2
+      // geometry index through the v3 runtime seam. The current L05
+      // index is projected from the render frame; callers still get
+      // renderer-neutral value objects and no DOM/PM/runtime instances.
+      return geometry?.getGeometryIndex() ?? null;
+    },
+
+    getGeometryCoverage(): GeometryIndexCoverage {
+      // @endStateApi — live-with-adapter. Coverage is intentionally
+      // total: an unwired/pre-paint handle reports an unavailable zero
+      // summary instead of null so evidence code can branch on status.
+      return geometry?.getGeometryCoverage() ?? createUnavailableGeometryCoverage();
+    },
+
     getBlockRects(blockIds: readonly string[]): ReadonlyArray<BlockRectEntry & Partial<MockPayload>> {
       // @endStateApi — live-with-adapter. Routes directly through the
       // Layer-05 GeometryFacet's `getBlockRects(blockId)`, which walks