@beyondwork/docx-react-component 1.0.102 → 1.0.104

package/src/runtime/formatting/layout-inputs.ts

@@ -0,0 +1,320 @@
+import type {
+  CanonicalParagraphFormatting,
+  CanonicalRunFormatting,
+  FieldFamily,
+  FieldRefreshStatus,
+  FieldRegistry,
+  FieldRegistryEntry,
+  TabStop,
+} from "../../model/canonical-document.ts";
+import {
+  MAIN_STORY_KEY,
+  type CanonicalFieldRegionIdentity,
+} from "../../model/canonical-layout-inputs.ts";
+import type { ResolvedField } from "./field/resolver.ts";
+import type {
+  EffectiveParagraphFormatting,
+  EffectiveRunFormatting,
+  EffectiveTableFormatting,
+  RevisionDisplayFlags,
+} from "./formatting-types.ts";
+import type { NumberingPrefixResult } from "./numbering/prefix.ts";
+
+export type LayoutMarkerSuffix = "tab" | "space" | "none";
+
+export interface LayoutTabStopInput {
+  readonly positionTwips: number;
+  readonly align: TabStop["align"];
+  readonly leader?: TabStop["leader"];
+  readonly source: "paragraph" | "numbering" | "toc";
+}
+
+export interface NumberingLayoutInput {
+  readonly markerText: string | null;
+  readonly markerRunFormatting?: CanonicalRunFormatting;
+  readonly markerSuffix: LayoutMarkerSuffix;
+  readonly markerLaneStartTwips?: number;
+  readonly markerLaneWidthTwips?: number;
+  readonly textColumnStartTwips?: number;
+  readonly hangingTwips?: number;
+  readonly associatedTabStops: readonly LayoutTabStopInput[];
+  readonly level: number;
+  readonly format: string;
+  readonly startAt: number;
+  readonly isLegalNumbering?: boolean;
+  readonly pictureBulletMediaId?: string;
+}
+
+export interface FieldLayoutInput {
+  readonly fieldId: string;
+  readonly regionId: string;
+  readonly regionKind: "field" | "toc-region";
+  readonly storyKey: string;
+  readonly fieldIndex: number;
+  readonly paragraphIndex: number;
+  readonly family: FieldFamily;
+  readonly instruction: string;
+  readonly cachedText: string;
+  readonly switches?: FieldRegistryEntry["switches"];
+  readonly targetBookmark?: string;
+  readonly refreshState: FieldRefreshStatus | "unresolved";
+  readonly resolvedText?: string;
+  readonly asHyperlink?: boolean;
+  readonly tocRegionId?: string;
+  readonly tocEntryCount?: number;
+}
+
+export interface RevisionLayoutPosture {
+  readonly mode: "clean" | "simple" | "all" | "original" | "no-markup";
+  /**
+   * True only when the active revision display changes measured text
+   * for the paragraph. Paint-only redline posture is compositor data,
+   * not an L04 measurement input.
+   */
+  readonly affectsMeasuredText: boolean;
+  readonly hiddenRevisionIds: readonly string[];
+  readonly visibleRevisionIds: readonly string[];
+}
+
+export interface EffectiveLayoutFormatting {
+  readonly paragraph?: EffectiveParagraphFormatting;
+  readonly runs: readonly EffectiveRunFormatting[];
+  readonly table?: EffectiveTableFormatting;
+  readonly cell?: {
+    readonly paragraph: CanonicalParagraphFormatting;
+    readonly run: CanonicalRunFormatting;
+  };
+  readonly numbering?: NumberingLayoutInput;
+  readonly tabs: readonly LayoutTabStopInput[];
+  readonly compatFlags: readonly string[];
+  readonly revisionPosture?: RevisionLayoutPosture;
+  readonly structuralHash: string;
+}
+
+export function normalizeNumberingMarkerSuffix(
+  suffix: NumberingPrefixResult["suffix"] | undefined,
+): LayoutMarkerSuffix {
+  if (suffix === "tab" || suffix === "space") return suffix;
+  return "none";
+}
+
+export function toLayoutTabStops(
+  tabStops: readonly TabStop[] | undefined,
+  source: LayoutTabStopInput["source"],
+): readonly LayoutTabStopInput[] {
+  if (!tabStops || tabStops.length === 0) return [];
+  return tabStops
+    .map((tabStop) => ({
+      positionTwips: tabStop.position,
+      align: tabStop.align,
+      ...(tabStop.leader ? { leader: tabStop.leader } : {}),
+      source,
+    }))
+    .sort((a, b) => a.positionTwips - b.positionTwips);
+}
+
+export function mergeLayoutTabStops(
+  ...groups: readonly (readonly LayoutTabStopInput[] | undefined)[]
+): readonly LayoutTabStopInput[] {
+  const byKey = new Map<string, LayoutTabStopInput>();
+  for (const group of groups) {
+    for (const tabStop of group ?? []) {
+      const key = [
+        tabStop.source,
+        tabStop.positionTwips,
+        tabStop.align,
+        tabStop.leader ?? "",
+      ].join(":");
+      byKey.set(key, tabStop);
+    }
+  }
+  return [...byKey.values()].sort((a, b) => {
+    if (a.positionTwips !== b.positionTwips) return a.positionTwips - b.positionTwips;
+    return a.source.localeCompare(b.source);
+  });
+}
+
+export function toNumberingLayoutInput(
+  numbering: NumberingPrefixResult | null | undefined,
+): NumberingLayoutInput | undefined {
+  if (!numbering) return undefined;
+  const markerLane = numbering.geometry.markerLane;
+  const textColumn = numbering.geometry.textColumn;
+  const hangingTwips =
+    textColumn?.hanging ??
+    numbering.geometry.indentation?.hanging ??
+    (typeof numbering.geometry.indentation?.firstLine === "number" &&
+    numbering.geometry.indentation.firstLine < 0
+      ? Math.abs(numbering.geometry.indentation.firstLine)
+      : undefined);
+
+  return {
+    markerText: numbering.text,
+    ...(numbering.markerRunProperties
+      ? { markerRunFormatting: numbering.markerRunProperties }
+      : {}),
+    markerSuffix: normalizeNumberingMarkerSuffix(numbering.suffix),
+    ...(markerLane ? { markerLaneStartTwips: markerLane.start } : {}),
+    ...(markerLane ? { markerLaneWidthTwips: markerLane.width } : {}),
+    ...(textColumn ? { textColumnStartTwips: textColumn.start } : {}),
+    ...(hangingTwips !== undefined ? { hangingTwips } : {}),
+    associatedTabStops: toLayoutTabStops(numbering.geometry.tabStops, "numbering"),
+    level: numbering.level,
+    format: numbering.format,
+    startAt: numbering.startAt,
+    ...(numbering.isLegalNumbering ? { isLegalNumbering: true } : {}),
+    ...(numbering.picBulletMediaId
+      ? { pictureBulletMediaId: numbering.picBulletMediaId }
+      : {}),
+  };
+}
+
+export function toFieldLayoutInput(
+  entry: FieldRegistryEntry,
+  resolved?: ResolvedField,
+  region?: CanonicalFieldRegionIdentity,
+): FieldLayoutInput {
+  return {
+    fieldId: `field-${entry.fieldIndex}`,
+    regionId: region?.regionId ?? `field:${entry.fieldIndex}`,
+    regionKind: region?.kind ?? "field",
+    storyKey: region?.storyKey ?? entry.storyKey ?? MAIN_STORY_KEY,
+    fieldIndex: entry.fieldIndex,
+    paragraphIndex: region?.paragraphIndex ?? entry.paragraphIndex,
+    family: entry.fieldFamily,
+    instruction: entry.instruction,
+    cachedText: entry.displayText,
+    ...(entry.switches ? { switches: entry.switches } : {}),
+    ...(entry.fieldTarget ? { targetBookmark: entry.fieldTarget } : {}),
+    refreshState: resolved?.refreshStatus ?? entry.refreshStatus ?? "unresolved",
+    ...(resolved?.displayText !== undefined ? { resolvedText: resolved.displayText } : {}),
+    ...(resolved?.asHyperlink ? { asHyperlink: true } : {}),
+  };
+}
+
+export function collectFieldLayoutInputs(
+  registry: FieldRegistry | undefined,
+  resolve?: (entry: FieldRegistryEntry) => ResolvedField | undefined,
+  regions: readonly CanonicalFieldRegionIdentity[] = [],
+): readonly FieldLayoutInput[] {
+  if (!registry) return [];
+  const inputs: FieldLayoutInput[] = [];
+  const entries = [...registry.supported, ...registry.preserveOnly];
+  const fieldRegions = new Map(
+    regions
+      .filter((region) => region.kind === "field")
+      .map((region) => [region.fieldIndex, region]),
+  );
+  const tocRegions = new Map(
+    regions
+      .filter((region) => region.kind === "toc-region" && region.tocId !== undefined)
+      .map((region) => [region.tocId!, region]),
+  );
+  for (const entry of entries) {
+    inputs.push(toFieldLayoutInput(entry, resolve?.(entry), fieldRegions.get(entry.fieldIndex)));
+  }
+  for (const region of registry.tocRegions ?? []) {
+    const source = registry.supported.find(
+      (entry) => entry.fieldIndex === region.sourceFieldIndex,
+    );
+    if (!source) continue;
+    const identity = tocRegions.get(region.tocId);
+    inputs.push({
+      ...toFieldLayoutInput(source, resolve?.(source), identity),
+      fieldId: `toc-${region.tocId}`,
+      family: "TOC",
+      instruction: region.instruction.raw,
+      cachedText: region.cachedEntries.map((entry) => entry.displayText).join("\n"),
+      refreshState: region.status === "current" ? "current" : "stale",
+      tocRegionId: region.tocId,
+      tocEntryCount: region.cachedEntries.length + region.generatedEntries.length,
+    });
+  }
+  return inputs;
+}
+
+export function buildRevisionLayoutPosture(
+  mode: RevisionLayoutPosture["mode"],
+  displays: readonly RevisionDisplayFlags[] = [],
+): RevisionLayoutPosture {
+  const hiddenRevisionIds = displays
+    .filter((display) => display.hidden === true)
+    .map((display) => display.revisionId);
+  const visibleRevisionIds = displays
+    .filter((display) => display.hidden !== true)
+    .map((display) => display.revisionId);
+  return {
+    mode,
+    affectsMeasuredText: hiddenRevisionIds.length > 0,
+    hiddenRevisionIds,
+    visibleRevisionIds,
+  };
+}
+
+export function toMeasuredRevisionLayoutPosture(
+  posture: RevisionLayoutPosture | undefined,
+): RevisionLayoutPosture | undefined {
+  if (!posture?.affectsMeasuredText || posture.hiddenRevisionIds.length === 0) {
+    return undefined;
+  }
+  return {
+    ...posture,
+    visibleRevisionIds: [],
+  };
+}
+
+export function buildEffectiveLayoutFormatting(input: {
+  readonly paragraph?: EffectiveParagraphFormatting;
+  readonly runs?: readonly EffectiveRunFormatting[];
+  readonly table?: EffectiveTableFormatting;
+  readonly cell?: {
+    readonly paragraph: CanonicalParagraphFormatting;
+    readonly run: CanonicalRunFormatting;
+  };
+  readonly numbering?: NumberingLayoutInput;
+  readonly tabs?: readonly LayoutTabStopInput[];
+  readonly compatFlags?: readonly string[];
+  readonly revisionPosture?: RevisionLayoutPosture;
+}): EffectiveLayoutFormatting {
+  const revisionPosture = toMeasuredRevisionLayoutPosture(input.revisionPosture);
+  const withoutHash = {
+    ...(input.paragraph ? { paragraph: input.paragraph } : {}),
+    runs: input.runs ?? [],
+    ...(input.table ? { table: input.table } : {}),
+    ...(input.cell ? { cell: input.cell } : {}),
+    ...(input.numbering ? { numbering: input.numbering } : {}),
+    tabs: input.tabs ?? [],
+    compatFlags: input.compatFlags ?? [],
+    ...(revisionPosture ? { revisionPosture } : {}),
+  };
+  return {
+    ...withoutHash,
+    structuralHash: createStructuralHash(withoutHash),
+  };
+}
+
+export function createStructuralHash(value: unknown): string {
+  const stable = stableStringify(value);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < stable.length; i += 1) {
+    hash ^= stable.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `fnv1a32:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record)
+    .filter((key) => record[key] !== undefined)
+    .sort();
+  return `{${keys
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+    .join(",")}}`;
+}

package/src/runtime/formatting/numbering/geometry.ts

@@ -8,6 +8,7 @@ import type {
   ParagraphNode,
   ParagraphSpacing,
   TabStop,
+  Mutable,
 } from "../../../model/canonical-document.ts";
 
 export const DEFAULT_NUMBERING_START_AT = 1;
@@ -52,7 +53,7 @@ export interface ResolvedNumberingDefinitionSet {
 }
 
 export function resolveNumberingDefinitionSet(
-  catalog: NumberingCatalog,
+  catalog: Mutable<NumberingCatalog>,
   numbering: ParagraphNode["numbering"] | undefined,
   paragraph?: Pick<ParagraphNode, "spacing" | "indentation" | "tabStops">,
 ): ResolvedNumberingDefinitionSet | null {
@@ -145,7 +146,7 @@ function mergeLevelDefinition(
   };
 }
 
-function withDefaultStartAt(level: NumberingLevelDefinition): NumberingLevelDefinition {
+function withDefaultStartAt(level: Mutable<NumberingLevelDefinition>): NumberingLevelDefinition {
   return {
     ...level,
     startAt: level.startAt ?? DEFAULT_NUMBERING_START_AT,
@@ -156,7 +157,7 @@ function withDefaultStartAt(level: NumberingLevelDefinition): NumberingLevelDefi
 }
 
 function cloneLevelParagraphGeometry(
-  geometry: NumberingLevelParagraphGeometry,
+  geometry: Mutable<NumberingLevelParagraphGeometry>,
 ): NumberingLevelParagraphGeometry {
   return {
     ...(geometry.justification ? { justification: geometry.justification } : {}),
@@ -244,7 +245,7 @@ function mergeParagraphSpacing(
     return undefined;
   }
 
-  const spacing: ParagraphSpacing = {
+  const spacing: Mutable<ParagraphSpacing> = {
     ...(base ?? {}),
     ...(override ?? {}),
   };
@@ -260,24 +261,24 @@ function mergeParagraphIndentation(
     return undefined;
   }
 
-  const out: ParagraphIndentation = {};
+  const out: Mutable<ParagraphIndentation> = {};
 
   const left = override?.left ?? base?.left;
-  if (left !== undefined) out.left = left;
+  if (left !== undefined) (out as Mutable<typeof out>).left = left;
 
   const right = override?.right ?? base?.right;
-  if (right !== undefined) out.right = right;
+  if (right !== undefined) (out as Mutable<typeof out>).right = right;
 
   // ECMA-376 §17.3.1.12: firstLine and hanging are mutually exclusive on a single
   // w:ind element. When override specifies either, it wins exclusively.
   const overrideTouchesFLorH =
     override?.firstLine !== undefined || override?.hanging !== undefined;
   if (overrideTouchesFLorH) {
-    if (override?.hanging !== undefined) out.hanging = override.hanging;
-    else if (override?.firstLine !== undefined) out.firstLine = override.firstLine;
+    if (override?.hanging !== undefined) (out as Mutable<typeof out>).hanging = override.hanging;
+    else if (override?.firstLine !== undefined) (out as Mutable<typeof out>).firstLine = override.firstLine;
   } else {
-    if (base?.hanging !== undefined) out.hanging = base.hanging;
-    else if (base?.firstLine !== undefined) out.firstLine = base.firstLine;
+    if (base?.hanging !== undefined) (out as Mutable<typeof out>).hanging = base.hanging;
+    else if (base?.firstLine !== undefined) (out as Mutable<typeof out>).firstLine = base.firstLine;
   }
 
   return Object.keys(out).length > 0 ? out : undefined;
@@ -333,7 +334,7 @@ function deriveTextColumn(
   };
 }
 
-function resolveHangingWidth(indentation: ParagraphIndentation): number | undefined {
+function resolveHangingWidth(indentation: Mutable<ParagraphIndentation>): number | undefined {
   if (indentation.hanging !== undefined) {
     return indentation.hanging;
   }

package/src/runtime/formatting/style-cascade.ts

@@ -28,6 +28,7 @@ import type {
   StylesCatalog,
   TableStyleConditionalRegion,
   TableStyleDefinition,
+  Mutable,
 } from "../../model/canonical-document.ts";
 import {
   resolveCharacterStyleChain,
@@ -51,7 +52,7 @@ export function mergeParagraph(
   over: CanonicalParagraphFormatting | undefined,
 ): CanonicalParagraphFormatting | undefined {
   if (!base && !over) return undefined;
-  const merged: CanonicalParagraphFormatting = { ...(base ?? {}), ...(over ?? {}) };
+  const merged: Mutable<CanonicalParagraphFormatting> = { ...(base ?? {}), ...(over ?? {}) };
   if (base?.spacing || over?.spacing) {
     merged.spacing = { ...(base?.spacing ?? {}), ...(over?.spacing ?? {}) };
   }

package/src/runtime/formatting/table-style-resolver.ts

@@ -10,6 +10,7 @@ import type {
   TableStyleDefinition,
   TableStyleFormatting,
   TableWidth,
+  Mutable,
 } from "../../model/canonical-document.ts";
 
 export interface ResolvedTableCellStyle {
@@ -58,7 +59,7 @@ export interface ResolvedTableStyleResolution {
   }>;
 }
 
-const DEFAULT_EFFECTIVE_TABLE_LOOK: TableLook = {
+const DEFAULT_EFFECTIVE_TABLE_LOOK: Mutable<TableLook> = {
   val: "04A0",
   firstRow: true,
   lastRow: false,
@@ -80,7 +81,7 @@ const CONDITIONAL_REGION_ORDER: TableStyleConditionalRegion[] = [
 ];
 
 export function resolveTableStyleResolution(
-  table: TableNode,
+  table: Mutable<TableNode>,
   tableStyles: Record<string, TableStyleDefinition>,
 ): ResolvedTableStyleResolution {
   const resolvedStyle = table.styleId ? resolveTableStyleDefinition(table.styleId, tableStyles) : {};
@@ -266,7 +267,7 @@ function decodeTableLookMask(val: string | undefined): TableLook | undefined {
 function getActiveRowRegions(
   rowIndex: number,
   rowCount: number,
-  effectiveTblLook: TableLook,
+  effectiveTblLook: Mutable<TableLook>,
 ): TableStyleConditionalRegion[] {
   const active = new Set<TableStyleConditionalRegion>();
 
@@ -294,7 +295,7 @@ function getActiveCellRegions(
   startColumn: number,
   endColumn: number,
   columnCount: number,
-  effectiveTblLook: TableLook,
+  effectiveTblLook: Mutable<TableLook>,
 ): TableStyleConditionalRegion[] {
   const active = new Set<TableStyleConditionalRegion>(rowRegions);
 
@@ -343,7 +344,7 @@ function mergeWholeStyleFormatting(
     return undefined;
   }
 
-  const merged: TableStyleFormatting = {};
+  const merged: Mutable<TableStyleFormatting> = {};
   const table = mergeTableFormatting(base?.table, override?.table);
   const row = mergeRowFormatting(base?.row, override?.row);
   const cell = mergeCellFormatting(base?.cell, override?.cell);
@@ -429,14 +430,14 @@ function mergeBorderMap<T extends TableBorders | TableCellBorders>(
   }
 
   const sides = ["top", "left", "bottom", "right", "insideH", "insideV"] as const;
-  const merged = {} as T;
+  const merged = {} as Mutable<T>;
   for (const side of sides) {
     const spec = mergePlainObject(base?.[side], override?.[side]) as BorderSpec | undefined;
     if (spec) {
       merged[side] = spec as T[typeof side];
     }
   }
-  return Object.keys(merged).length > 0 ? merged : undefined;
+  return Object.keys(merged).length > 0 ? (merged as T) : undefined;
 }
 
 function mergePlainObject<T extends object>(base: T | undefined, override: T | undefined): T | undefined {

package/src/runtime/geometry/caret-geometry.ts

@@ -37,6 +37,7 @@ import type { EditorStoryTarget } from "../../api/public-types";
 import type {
   RenderFrame,
   RenderFrameRect,
+  RenderStoryRegion,
 } from "../render/index.ts";
 import type {
   CaretGeometry,
@@ -86,12 +87,14 @@ export function resolveCaretGeometry(
  * Resolve `GeometryRect[]` for a selection range. Slice 4 produces:
  *   - an empty list when either endpoint can't be resolved
  *   - a single zero-width caret rect when `from === to`
+ *   - one line rect per covered render line when line ranges are available
  *   - a single union rect otherwise (via `frame.anchorIndex.bySelection`)
  *
- * When the kernel's per-line anchor projection matures (Slice 5+), this
- * function flips to emitting one rect per line. The single-rect fallback
- * keeps chrome surfaces that currently call `getAnchorRects({ kind:
- * "runtime-offset", … })[0]` in sync with the new selection API.
+ * The line-aware path still tags rects `within-tolerance`: without per-run
+ * anchors we can identify covered lines but not the first/last glyph bounds.
+ * The single-rect fallback keeps chrome surfaces that currently call
+ * `getAnchorRects({ kind: "runtime-offset", … })[0]` in sync with the
+ * selection API when a frame lacks line boxes.
  */
 export function resolveSelectionRects(
   frame: RenderFrame | null,
@@ -119,14 +122,11 @@ export function resolveSelectionRects(
     return [caret.rect];
   }
 
+  const lineRects = resolveLineSelectionRects(frame, lo, hi, range.story);
+  if (lineRects.length > 0) return lineRects;
+
   const union = frame.anchorIndex.bySelection(lo, hi, range.story);
   if (!union) return [];
-  // Slice 7b (2026-04-22): the substrate returns ONE union rect for any
-  // non-collapsed range. That rect is geometrically correct at the
-  // block level but loses per-line detail — tag it `within-tolerance`
-  // so callers can gate per-line chrome work. When the render kernel
-  // ships per-run anchors (refactor/05 Slice 7 Task 2), this site
-  // upgrades to multiple `"exact"` rects automatically.
   return [toGeometryRect(union, "within-tolerance")];
 }
 
@@ -151,6 +151,78 @@ function toGeometryRect(
   return out;
 }
 
+function resolveLineSelectionRects(
+  frame: RenderFrame,
+  from: number,
+  to: number,
+  story?: EditorStoryTarget,
+): readonly GeometryRect[] {
+  if (!Array.isArray(frame.pages)) return [];
+  const rects: GeometryRect[] = [];
+  for (const page of frame.pages) {
+    for (const region of collectRegions(page.regions)) {
+      if (!storyMatches(region.storyTarget, story)) continue;
+      for (const block of region.blocks) {
+        const blockFrom = block.fragment.from;
+        const blockTo = block.fragment.to;
+        if (blockTo <= from || blockFrom >= to) continue;
+        if (block.lines.length === 0) continue;
+        const lineCount = block.lines.length;
+        const span = Math.max(1, blockTo - blockFrom);
+        for (let i = 0; i < lineCount; i += 1) {
+          const line = block.lines[i]!;
+          const lineFrom =
+            blockFrom + Math.floor((span * i) / Math.max(1, lineCount));
+          const lineTo =
+            i === lineCount - 1
+              ? blockTo
+              : blockFrom +
+                Math.floor((span * (i + 1)) / Math.max(1, lineCount));
+          if (lineTo <= from || lineFrom >= to) continue;
+          rects.push(toGeometryRect(line.frame, "within-tolerance"));
+        }
+      }
+    }
+  }
+  return rects;
+}
+
+function collectRegions(
+  regions: RenderFrame["pages"][number]["regions"],
+): readonly RenderStoryRegion[] {
+  return [
+    regions.body,
+    regions.header,
+    regions.footer,
+    ...(regions.columns ?? []),
+    regions.footnoteArea,
+    ...(regions.footnotes ?? []),
+  ].filter((region): region is RenderStoryRegion => Boolean(region));
+}
+
+function storyMatches(
+  actual: EditorStoryTarget,
+  expected: EditorStoryTarget | undefined,
+): boolean {
+  if (!expected) return true;
+  if (actual.kind !== expected.kind) return false;
+  switch (expected.kind) {
+    case "main":
+      return true;
+    case "header":
+    case "footer":
+      return (
+        "relationshipId" in actual &&
+        actual.relationshipId === expected.relationshipId &&
+        actual.variant === expected.variant &&
+        actual.sectionIndex === expected.sectionIndex
+      );
+    case "footnote":
+    case "endnote":
+      return "noteId" in actual && actual.noteId === expected.noteId;
+  }
+}
+
 /**
  * Approximate the baseline offset within a line rect. The render frame
  * does not yet carry per-anchor baseline metadata, so Slice 4 uses a

package/src/runtime/geometry/geometry-facet.ts

@@ -37,6 +37,8 @@ import type {
   BlockGeometry,
   CaretGeometry,
   EnvelopeBundle,
+  GeometryIndex,
+  GeometryIndexCoverage,
   GeometryRect,
   HitTestPoint,
   HitTestResult,
@@ -51,6 +53,11 @@ import {
 import { resolveHitTest } from "./hit-test.ts";
 import { resolveObjectHandles } from "./object-handles.ts";
 import { resolveAnchorRects } from "./project-anchors.ts";
+import {
+  createUnavailableGeometryCoverage,
+  projectGeometryIndexFromFrame,
+  summarizeGeometryCoverageFromFrame,
+} from "./geometry-index.ts";
 import {
   resolveReplacementEnvelope,
   type ReplacementScope,
@@ -67,6 +74,21 @@ import { createViewport, type ViewportHandle } from "./viewport.ts";
 // ---------------------------------------------------------------------------
 
 export interface GeometryFacet {
+  // PE2 index / coverage -------------------------------------------------
+  /**
+   * Renderer-neutral geometry index for the current frame. This is the PE2
+   * Slice-1 substrate: pages, regions, slices, lines, anchors, hit targets,
+   * and coverage metadata. Returns null when no render kernel/frame is warm.
+   */
+  getGeometryIndex(): GeometryIndex | null;
+
+  /**
+   * Lightweight coverage summary for evidence/debug consumers. Unlike
+   * `getGeometryIndex`, this always returns a value; unwired/pre-paint states
+   * report `status: "unavailable"` with zero counts.
+   */
+  getGeometryCoverage(): GeometryIndexCoverage;
+
   // Hit-test -------------------------------------------------------------
   /**
    * Resolve a point in the shell's overlay coordinate space to a canonical
@@ -226,6 +248,20 @@ export function createGeometryFacet(
   const viewport = input.viewport ?? createViewport();
 
   return {
+    getGeometryIndex() {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return null;
+      return projectGeometryIndexFromFrame(kernel.getRenderFrame(), {
+        canonicalDocument: input.getCanonicalDocument?.() ?? null,
+      });
+    },
+
+    getGeometryCoverage() {
+      const kernel = input.renderKernel?.();
+      if (!kernel) return createUnavailableGeometryCoverage();
+      return summarizeGeometryCoverageFromFrame(kernel.getRenderFrame());
+    },
+
     hitTest(point) {
       // Slice 6 wrapper-deletion (2026-04-22): the layout-facet fallback
       // was deleted. `hitTest` now resolves only through the render-kernel