@beyondwork/docx-react-component 1.0.106 → 1.0.109

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

@@ -5,10 +5,16 @@
  * `load` (partial — runtime pre-load is the caller's responsibility; v3
  * exposes a re-mount semantic later), `getMode` / `setMode` (live;
  * delegates to the runtime view-state posture), `export` (live; delegates
- * to `runtime.exportDocx`), `validate` (partial; read live, write mock).
+ * to `runtime.exportDocx`), `validate` / `getExportSafety`
+ * (live-with-adapter reads).
  */
 
-import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type {
+  RuntimeApiHandle,
+  RuntimeWordFieldMatrixArtifact,
+  RuntimeWordFieldMatrixComparisonLane,
+  RuntimeWordFieldMatrixRow,
+} from "../_runtime-handle.ts";
 import type {
   DocumentMode,
   EditorError,
@@ -163,6 +169,99 @@ export interface ValidateResult {
   readonly __mock?: true;
 }
 
+interface CompatibilityReadModel {
+  readonly reportVersion?: "compatibility-report/1";
+  readonly blockExport?: boolean;
+  readonly blockExportReasons?: readonly string[];
+  readonly warningCount?: number;
+  readonly errorCount?: number;
+  readonly featureEntries?: ReadonlyArray<unknown>;
+  readonly warnings?: ReadonlyArray<unknown>;
+  readonly errors?: ReadonlyArray<unknown>;
+}
+
+interface InteractionGuardReadModel {
+  readonly mode?: string;
+  readonly readOnly?: boolean;
+  readonly effectiveMode?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOptionalBoolean(record: Record<string, unknown>, key: string): boolean {
+  return record[key] === undefined || typeof record[key] === "boolean";
+}
+
+function hasOptionalNumber(record: Record<string, unknown>, key: string): boolean {
+  return record[key] === undefined || typeof record[key] === "number";
+}
+
+function hasOptionalArray(record: Record<string, unknown>, key: string): boolean {
+  return record[key] === undefined || Array.isArray(record[key]);
+}
+
+function isCompatibilityReadModel(value: unknown): value is CompatibilityReadModel {
+  if (!isRecord(value)) return false;
+  if (
+    value.reportVersion !== undefined &&
+    value.reportVersion !== "compatibility-report/1"
+  ) {
+    return false;
+  }
+  return (
+    hasOptionalBoolean(value, "blockExport") &&
+    hasOptionalArray(value, "blockExportReasons") &&
+    hasOptionalNumber(value, "warningCount") &&
+    hasOptionalNumber(value, "errorCount") &&
+    hasOptionalArray(value, "featureEntries") &&
+    hasOptionalArray(value, "warnings") &&
+    hasOptionalArray(value, "errors")
+  );
+}
+
+export interface ExportSafetyCitation {
+  readonly citationId: string;
+  readonly source:
+    | "compatibility-report"
+    | "compatibility-error"
+    | "compatibility-warning"
+    | "runtime-warning"
+    | "interaction-guard"
+    | "render-snapshot";
+  readonly path: string;
+  readonly code: string;
+  readonly message: string;
+  readonly blocksExport: boolean;
+}
+
+export interface ExportSafetyResult {
+  readonly validation: {
+    readonly reportVersion: "compatibility-report/1";
+    readonly blockExport: boolean;
+    readonly warningCount: number;
+    readonly errorCount: number;
+    readonly featureEntriesCount: number;
+  };
+  readonly exportSafety: {
+    readonly canExport: boolean;
+    readonly blockedBy: readonly string[];
+    readonly blockExportReasons: readonly string[];
+    readonly citations: readonly ExportSafetyCitation[];
+  };
+  readonly mutationState: {
+    readonly documentMode: string;
+    readonly readOnly: boolean;
+    readonly mutationSuccessImpliesExportSafety: false;
+  };
+  readonly interactionGuard: {
+    readonly mode: string;
+    readonly readOnly: boolean;
+  };
+  readonly __mock?: true;
+}
+
 export const validateMetadata: ApiV3FnMetadata = {
   name: "runtime.document.validate",
   status: "live-with-adapter",
@@ -185,6 +284,358 @@ export const validateMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.document.validate. Adapter composes three shipped runtime reads — getCompatibilityReport() + getWarnings() + getInteractionGuardSnapshot() — into one bundled ValidateResult. Promotes to `live` when a first-class runtime.validate() lands.",
 };
 
+export const getExportSafetyMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.getExportSafety",
+  status: "live-with-adapter",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/behavioral-coverage.test.ts",
+    commit: "refactor-07-export-safety-read",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "hash",
+    shapeDescription:
+      "Fallback ExportSafetyResult with zeroed validation counts and canExport=true when compatibility and guard reads are both unavailable.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "document-export-safety",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.document.getExportSafety. Adapter composes getCompatibilityReport() + getRenderSnapshot().compatibility + getWarnings() + getInteractionGuardSnapshot() into distinct validation/exportSafety/mutationState sections plus citation rows for blockers and warnings, so callers do not infer export readiness from mutation success or from runtime.document.validate alone.",
+};
+
+export interface WordFieldMatrixResult {
+  readonly schemaVersion: "pe2-word-field-matrix/v0";
+  readonly artifactKind: "pe2.word-field-matrix";
+  readonly status: "available" | "unavailable";
+  readonly source: "debug-word-field-matrix" | "debug-word-field-matrix-unavailable";
+  readonly reason?: "provider-unavailable" | "artifact-unavailable";
+  readonly doc?: RuntimeWordFieldMatrixArtifact["doc"];
+  readonly generatedAtUtc?: string;
+  readonly word?: RuntimeWordFieldMatrixArtifact["word"];
+  readonly summary: RuntimeWordFieldMatrixArtifact["summary"];
+  readonly rows: readonly RuntimeWordFieldMatrixRow[];
+  readonly __mock?: true;
+}
+
+export const getWordFieldMatrixMetadata: ApiV3FnMetadata = {
+  name: "runtime.document.getWordFieldMatrix",
+  status: "live-with-adapter",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-07-word-field-matrix-readback",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Unavailable pe2.word-field-matrix envelope when no debug evidence provider is wired on the RuntimeApiHandle.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "word-field-matrix",
+    contextPromptShape:
+      "Word-first PE2 field matrix rows with owning layer, Word status, comparison lanes, and routing note.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.document.getWordFieldMatrix. Optional host-wired readback of debug `pe2.word-field-matrix` evidence. Returns plain row/status/provenance values only; product runtime does not synthesize Word COM evidence or route VM runner data.",
+};
+
+const WORD_FIELD_MATRIX_OWNER_ZEROES = {
+  L01: 0,
+  L02: 0,
+  L03: 0,
+  L04: 0,
+  L05: 0,
+  L06: 0,
+  L08: 0,
+  L11: 0,
+} as const;
+
+const WORD_FIELD_MATRIX_GROUP_ZEROES = {
+  structuralSummary: 0,
+  pageGeometry: 0,
+  tableContinuations: 0,
+  fields: 0,
+  legalNumberingSamples: 0,
+  anchorsAndObjects: 0,
+  packagePreservation: 0,
+  reviewMarkup: 0,
+} as const;
+
+function copyWordFieldComparisonLane(
+  lane: RuntimeWordFieldMatrixComparisonLane,
+): RuntimeWordFieldMatrixComparisonLane {
+  return {
+    status: lane.status,
+    ...(lane.evidencePath ? { evidencePath: lane.evidencePath } : {}),
+    ...(lane.note ? { note: lane.note } : {}),
+  };
+}
+
+function copyWordFieldMatrixRow(row: RuntimeWordFieldMatrixRow): RuntimeWordFieldMatrixRow {
+  return {
+    group: row.group,
+    field: row.field,
+    primaryOwner: row.primaryOwner,
+    wordStatus: row.wordStatus,
+    wordEvidencePath: row.wordEvidencePath,
+    comparison: {
+      ...(row.comparison.libreOffice
+        ? { libreOffice: copyWordFieldComparisonLane(row.comparison.libreOffice) }
+        : {}),
+      ...(row.comparison.sourcePackage
+        ? { sourcePackage: copyWordFieldComparisonLane(row.comparison.sourcePackage) }
+        : {}),
+      ...(row.comparison.graphPdf
+        ? { graphPdf: copyWordFieldComparisonLane(row.comparison.graphPdf) }
+        : {}),
+    },
+    routingNote: row.routingNote,
+  };
+}
+
+function unavailableWordFieldMatrix(reason: "provider-unavailable" | "artifact-unavailable") {
+  return mockPayload(reason, "WordFieldMatrixResult", {
+    schemaVersion: "pe2-word-field-matrix/v0" as const,
+    artifactKind: "pe2.word-field-matrix" as const,
+    status: "unavailable" as const,
+    source: "debug-word-field-matrix-unavailable" as const,
+    reason,
+    summary: {
+      rowCount: 0,
+      available: 0,
+      partial: 0,
+      missing: 0,
+      byOwner: WORD_FIELD_MATRIX_OWNER_ZEROES,
+      byGroup: WORD_FIELD_MATRIX_GROUP_ZEROES,
+    },
+    rows: [] as readonly RuntimeWordFieldMatrixRow[],
+  });
+}
+
+function projectWordFieldMatrix(
+  artifact: RuntimeWordFieldMatrixArtifact,
+): WordFieldMatrixResult {
+  return {
+    schemaVersion: artifact.schemaVersion,
+    artifactKind: artifact.artifactKind,
+    status: "available",
+    source: "debug-word-field-matrix",
+    doc: {
+      docId: artifact.doc.docId,
+      corpusLane: artifact.doc.corpusLane,
+      ...(artifact.doc.sourceSha256 ? { sourceSha256: artifact.doc.sourceSha256 } : {}),
+    },
+    generatedAtUtc: artifact.generatedAtUtc,
+    word: {
+      status: artifact.word.status,
+      ...(artifact.word.oracleName ? { oracleName: artifact.word.oracleName } : {}),
+      ...(artifact.word.backend ? { backend: artifact.word.backend } : {}),
+      ...(artifact.word.recordPath ? { recordPath: artifact.word.recordPath } : {}),
+      ...(artifact.word.unavailableReason
+        ? { unavailableReason: artifact.word.unavailableReason }
+        : {}),
+    },
+    summary: {
+      rowCount: artifact.summary.rowCount,
+      available: artifact.summary.available,
+      partial: artifact.summary.partial,
+      missing: artifact.summary.missing,
+      byOwner: { ...artifact.summary.byOwner },
+      byGroup: { ...artifact.summary.byGroup },
+    },
+    rows: artifact.rows.map(copyWordFieldMatrixRow),
+  };
+}
+
+function readCompatibilitySnapshot(runtime: RuntimeApiHandle): {
+  readonly compatibility: CompatibilityReadModel | null;
+  readonly warnings: ReadonlyArray<unknown>;
+  readonly guard: InteractionGuardReadModel | null;
+  readonly documentMode: string;
+  readonly readOnly: boolean;
+} {
+  const reportValue = runtime.getCompatibilityReport();
+  const report: CompatibilityReadModel | null = isCompatibilityReadModel(reportValue)
+    ? reportValue
+    : null;
+  const snapshot = runtime.getRenderSnapshot();
+  const snapshotCompatValue: unknown = snapshot.compatibility;
+  const snapshotCompat: CompatibilityReadModel | null = isCompatibilityReadModel(snapshotCompatValue)
+    ? snapshotCompatValue
+    : null;
+  const guard = runtime.getInteractionGuardSnapshot() as InteractionGuardReadModel | undefined | null;
+  const compatibility: CompatibilityReadModel | null = report
+    ? {
+        ...snapshotCompat,
+        ...report,
+        blockExportReasons: report.blockExportReasons ?? snapshotCompat?.blockExportReasons,
+      }
+    : snapshotCompat ?? null;
+  return {
+    compatibility,
+    warnings: runtime.getWarnings(),
+    guard: guard ?? null,
+    documentMode: snapshot.documentMode ?? "unknown",
+    readOnly: snapshot.readOnly ?? guard?.readOnly ?? false,
+  };
+}
+
+function countWarnings(
+  compatibility: CompatibilityReadModel | null,
+  runtimeWarnings: ReadonlyArray<unknown>,
+): number {
+  const compatCount = typeof compatibility?.warningCount === "number"
+    ? compatibility.warningCount
+    : compatibility?.warnings?.length ?? 0;
+  return compatCount + runtimeWarnings.length;
+}
+
+function countErrors(compatibility: CompatibilityReadModel | null): number {
+  return typeof compatibility?.errorCount === "number"
+    ? compatibility.errorCount
+    : compatibility?.errors?.length ?? 0;
+}
+
+function asIssue(value: unknown): { readonly code?: string; readonly message?: string } {
+  return value && typeof value === "object"
+    ? value as { readonly code?: string; readonly message?: string }
+    : {};
+}
+
+function buildExportSafetyCitations(
+  compatibility: CompatibilityReadModel | null,
+  runtimeWarnings: ReadonlyArray<unknown>,
+  guard: InteractionGuardReadModel | null,
+  blockExportReasons: readonly string[],
+): readonly ExportSafetyCitation[] {
+  const citations: ExportSafetyCitation[] = [];
+
+  for (let index = 0; index < blockExportReasons.length; index += 1) {
+    const reason = blockExportReasons[index];
+    citations.push({
+      citationId: `export-safety:block-export-reason:${index}`,
+      source: "compatibility-report",
+      path: `compatibility.blockExportReasons[${index}]`,
+      code: "compatibility:block-export",
+      message: reason,
+      blocksExport: true,
+    });
+  }
+
+  for (let index = 0; index < (compatibility?.errors?.length ?? 0); index += 1) {
+    const issue = asIssue(compatibility?.errors?.[index]);
+    citations.push({
+      citationId: `export-safety:compatibility-error:${index}`,
+      source: "compatibility-error",
+      path: `compatibility.errors[${index}]`,
+      code: issue.code ?? "validation:errors",
+      message: issue.message ?? "Compatibility validation error blocks export.",
+      blocksExport: true,
+    });
+  }
+
+  for (let index = 0; index < (compatibility?.warnings?.length ?? 0); index += 1) {
+    const issue = asIssue(compatibility?.warnings?.[index]);
+    citations.push({
+      citationId: `export-safety:compatibility-warning:${index}`,
+      source: "compatibility-warning",
+      path: `compatibility.warnings[${index}]`,
+      code: issue.code ?? "validation:warning",
+      message: issue.message ?? "Compatibility validation warning.",
+      blocksExport: false,
+    });
+  }
+
+  for (let index = 0; index < runtimeWarnings.length; index += 1) {
+    const warning = asIssue(runtimeWarnings[index]);
+    citations.push({
+      citationId: `export-safety:runtime-warning:${index}`,
+      source: "runtime-warning",
+      path: `runtime.warnings[${index}]`,
+      code: warning.code ?? "runtime:warning",
+      message: warning.message ?? "Runtime warning.",
+      blocksExport: false,
+    });
+  }
+
+  if (guard?.readOnly === true) {
+    citations.push({
+      citationId: "export-safety:interaction-guard:read-only",
+      source: "interaction-guard",
+      path: "interactionGuard.readOnly",
+      code: "interaction-guard:read-only",
+      message: "The current interaction guard is read-only; mutation success is not proof of export readiness.",
+      blocksExport: false,
+    });
+  }
+
+  return citations;
+}
+
+function buildExportSafetyResult(
+  runtime: RuntimeApiHandle,
+): (ExportSafetyResult & Partial<MockPayload>) | null {
+  const { compatibility, warnings, guard, documentMode, readOnly } =
+    readCompatibilitySnapshot(runtime);
+  if (!compatibility && !guard) return null;
+
+  const blockExport = compatibility?.blockExport ?? false;
+  const warningCount = countWarnings(compatibility, warnings);
+  const errorCount = countErrors(compatibility);
+  const featureEntriesCount = compatibility?.featureEntries?.length ?? 0;
+  const blockExportReasons = compatibility?.blockExportReasons ?? [];
+  const blockedBy = [
+    ...(blockExport ? ["compatibility:block-export"] : []),
+    ...(errorCount > 0 ? ["validation:errors"] : []),
+  ];
+  const citations = buildExportSafetyCitations(
+    compatibility,
+    warnings,
+    guard,
+    blockExportReasons,
+  );
+
+  return {
+    validation: {
+      reportVersion: "compatibility-report/1",
+      blockExport,
+      warningCount,
+      errorCount,
+      featureEntriesCount,
+    },
+    exportSafety: {
+      canExport: blockedBy.length === 0,
+      blockedBy,
+      blockExportReasons,
+      citations,
+    },
+    mutationState: {
+      documentMode,
+      readOnly,
+      mutationSuccessImpliesExportSafety: false,
+    },
+    interactionGuard: {
+      mode: guard?.mode ?? guard?.effectiveMode ?? "unknown",
+      readOnly: guard?.readOnly ?? readOnly,
+    },
+  };
+}
+
 /* ================================================================== */
 /*  family factory                                                    */
 /* ================================================================== */
@@ -268,6 +719,52 @@ export function createDocumentFamily(runtime: RuntimeApiHandle) {
       return result;
     },
 
+    getExportSafety(): ExportSafetyResult & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Separates validation facts from
+      // export readiness and from the latest document-mode/mutation posture.
+      // This is a read-only preflight: it never calls exportDocx().
+      const result = buildExportSafetyResult(runtime);
+      if (result) return result;
+      return mockPayload(
+        "no compatibility report or interaction guard available (pre-mount or test double)",
+        "ExportSafetyResult",
+        {
+          validation: {
+            reportVersion: "compatibility-report/1" as const,
+            blockExport: false,
+            warningCount: 0,
+            errorCount: 0,
+            featureEntriesCount: 0,
+          },
+          exportSafety: {
+            canExport: true,
+            blockedBy: [] as readonly string[],
+            blockExportReasons: [] as readonly string[],
+            citations: [] as readonly ExportSafetyCitation[],
+          },
+          mutationState: {
+            documentMode: "unknown",
+            readOnly: false,
+            mutationSuccessImpliesExportSafety: false as const,
+          },
+          interactionGuard: { mode: "unknown", readOnly: false },
+        },
+      );
+    },
+
+    getWordFieldMatrix(): WordFieldMatrixResult & Partial<MockPayload> {
+      // @endStateApi — live-with-adapter. Projects a host-wired debug
+      // `pe2.word-field-matrix` artifact into the runtime API as plain
+      // row/status/provenance values. Product runtime does not build,
+      // fetch, or refresh Word COM evidence.
+      const artifact = runtime.wordFieldMatrix?.getWordFieldMatrix();
+      if (!artifact) return unavailableWordFieldMatrix("provider-unavailable");
+      if (artifact.artifactKind !== "pe2.word-field-matrix") {
+        return unavailableWordFieldMatrix("artifact-unavailable");
+      }
+      return projectWordFieldMatrix(artifact);
+    },
+
     validate(): ValidateResult & Partial<MockPayload> {
       // @endStateApi — live-with-adapter. Composes three shipped runtime
       // reads into a bundled ValidateResult:
@@ -278,22 +775,8 @@ export function createDocumentFamily(runtime: RuntimeApiHandle) {
       // Falls back to a mock-flagged shape only when both the compat read
       // and the guard read are unavailable (e.g. pre-mount). The adapter
       // promotes to `live` when a first-class runtime.validate() surfaces.
-      const report = runtime.getCompatibilityReport() as
-        | {
-            blockExport?: boolean;
-            warningCount?: number;
-            errorCount?: number;
-            featureEntries?: ReadonlyArray<unknown>;
-          }
-        | undefined
-        | null;
-      const snapshotCompat = runtime.getRenderSnapshot().compatibility;
-      const bundledReport = report ?? snapshotCompat;
-      const warnings = runtime.getWarnings();
-      const guard = runtime.getInteractionGuardSnapshot() as
-        | { mode?: string; readOnly?: boolean }
-        | undefined
-        | null;
+      const { compatibility: bundledReport, warnings, guard } =
+        readCompatibilitySnapshot(runtime);
       if (!bundledReport && !guard) {
         const fallback = mockPayload(
           "no compatibility report or interaction guard available (pre-mount or test double)",
@@ -319,8 +802,8 @@ export function createDocumentFamily(runtime: RuntimeApiHandle) {
       const result: ValidateResult = {
         reportVersion: "compatibility-report/1",
         blockExport: bundledReport?.blockExport ?? false,
-        warningCount: (bundledReport?.warningCount ?? 0) + warnings.length,
-        errorCount: bundledReport?.errorCount ?? 0,
+        warningCount: countWarnings(bundledReport, warnings),
+        errorCount: countErrors(bundledReport),
         featureEntriesCount: bundledReport?.featureEntries?.length ?? 0,
         interactionGuard: {
           mode: guard?.mode ?? "unknown",

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

@@ -18,20 +18,28 @@ import type { MockPayload } from "../_layer-metadata.ts";
 import type {
   GeometryIndex,
   GeometryIndexCoverage,
+  GeometryIndexSlice,
+  GeometryPrecision,
+  GeometrySourceIdentity,
+  GeometrySpace,
 } from "../../../runtime/geometry/index.ts";
 
 function createUnavailableGeometryCoverage(): GeometryIndexCoverage {
   return {
     status: "unavailable",
     pageCount: 0,
+    pageFrameCompleteness: { complete: 0, partial: 0, absent: 0 },
     regionCount: 0,
     sliceCount: 0,
     lineCount: 0,
     anchorCount: 0,
     hitTargetCount: 0,
     semanticEntryCount: 0,
+    pageLocalFieldLedgerCount: 0,
     replacementEnvelopeCount: 0,
     objectHandleCount: 0,
+    layoutDivergenceObjectCount: 0,
+    splitRowCarryCount: 0,
     precision: { exact: 0, "within-tolerance": 0, heuristic: 0 },
   };
 }
@@ -121,6 +129,57 @@ export const getGeometryCoverageMetadata: ApiV3FnMetadata = {
     "§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.",
 };
 
+export interface GetPageSlicesOptions {
+  readonly pageIndex?: number;
+  readonly pageId?: string;
+  readonly regionKind?: GeometryIndexSlice["regionKind"];
+  readonly blockId?: string;
+  readonly scopeId?: string;
+}
+
+export interface V3PageSliceRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly space: GeometrySpace;
+  readonly precision?: GeometryPrecision;
+}
+
+export interface V3PageSlice {
+  readonly sliceId: string;
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly regionId: string;
+  readonly regionKind: GeometryIndexSlice["regionKind"];
+  readonly blockId: string;
+  readonly fragmentId: string;
+  readonly kind: GeometryIndexSlice["kind"];
+  readonly rect: V3PageSliceRect;
+  readonly lineIds: readonly string[];
+  readonly sourceIdentity?: GeometrySourceIdentity;
+}
+
+export const getPageSlicesMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getPageSlices",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-pe2-page-slice-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.getPageSlices. PE2 read surface over GeometryFacet.getGeometryIndex().slices. Returns immutable page-local slice values filtered by pageIndex/pageId/regionKind/blockId/sourceIdentity.scopeId, or [] when no geometry index is warm. This is the narrow public page-slice API over the Layer-05 geometry index; callers do not receive raw GeometryIndexSlice references.",
+};
+
 /* ================================================================== */
 /*  getCaret — Slice-4 caret geometry (Slice X3 of §4 of coord-05)    */
 /* ================================================================== */
@@ -303,6 +362,44 @@ export function createGeometryFamily(runtime: RuntimeApiHandle) {
       return geometry?.getGeometryCoverage() ?? createUnavailableGeometryCoverage();
     },
 
+    getPageSlices(options: GetPageSlicesOptions = {}): readonly V3PageSlice[] {
+      // @endStateApi — live-with-adapter. Provides the narrow v3
+      // page-slice read surface over L05 GeometryIndex.slices. The
+      // adapter clones each value so callers cannot mutate the geometry
+      // index retained by the runtime facet.
+      const index = geometry?.getGeometryIndex();
+      if (!index) return [];
+      return index.slices
+        .filter((slice) => {
+          if (options.pageIndex !== undefined && slice.pageIndex !== options.pageIndex) return false;
+          if (options.pageId !== undefined && slice.pageId !== options.pageId) return false;
+          if (options.regionKind !== undefined && slice.regionKind !== options.regionKind) return false;
+          if (options.blockId !== undefined && slice.blockId !== options.blockId) return false;
+          if (options.scopeId !== undefined && slice.sourceIdentity?.scopeId !== options.scopeId) return false;
+          return true;
+        })
+        .map((slice) => ({
+          sliceId: slice.sliceId,
+          pageId: slice.pageId,
+          pageIndex: slice.pageIndex,
+          regionId: slice.regionId,
+          regionKind: slice.regionKind,
+          blockId: slice.blockId,
+          fragmentId: slice.fragmentId,
+          kind: slice.kind,
+          rect: {
+            x: slice.rect.leftPx,
+            y: slice.rect.topPx,
+            width: slice.rect.widthPx,
+            height: slice.rect.heightPx,
+            space: slice.rect.space,
+            ...(slice.rect.precision !== undefined ? { precision: slice.rect.precision } : {}),
+          },
+          lineIds: [...slice.lineIds],
+          ...(slice.sourceIdentity !== undefined ? { sourceIdentity: { ...slice.sourceIdentity } } : {}),
+        }));
+    },
+
     getBlockRects(blockIds: readonly string[]): ReadonlyArray<BlockRectEntry & Partial<MockPayload>> {
       // @endStateApi — live-with-adapter. Routes directly through the
       // Layer-05 GeometryFacet's `getBlockRects(blockId)`, which walks