@beyondwork/docx-react-component 1.0.109 → 1.0.111

package/src/runtime/layout/resolve-page-previews.ts

@@ -31,6 +31,16 @@ export interface PagePreviewMaps {
   footerPreviewByPageId: Map<string, string>;
 }
 
+type PageLocalFieldLedger = readonly {
+  readonly family: string;
+  readonly displayText: string;
+}[];
+
+interface PagePreviewFieldState {
+  readonly ledger: PageLocalFieldLedger | undefined;
+  ordinal: number;
+}
+
 export function buildPagePreviewMaps(
   graph: RuntimePageGraph,
   subParts: {
@@ -49,7 +59,10 @@ export function buildPagePreviewMaps(
       if (source) {
         headerPreviewByPageId.set(
           page.pageId,
-          flattenBlocksToPreview(source.blocks, page, graph),
+          flattenBlocksToPreview(source.blocks, page, graph, {
+            ledger: findPageLocalStoryFieldLedger(page, headerStory),
+            ordinal: 0,
+          }),
         );
       }
     }
@@ -59,7 +72,10 @@ export function buildPagePreviewMaps(
       if (source) {
         footerPreviewByPageId.set(
           page.pageId,
-          flattenBlocksToPreview(source.blocks, page, graph),
+          flattenBlocksToPreview(source.blocks, page, graph, {
+            ledger: findPageLocalStoryFieldLedger(page, footerStory),
+            ordinal: 0,
+          }),
         );
       }
     }
@@ -76,14 +92,30 @@ function findSubPart<T extends HeaderDocument | FooterDocument>(
   return parts.find((p) => p.relationshipId === relationshipId);
 }
 
+function findPageLocalStoryFieldLedger(
+  page: RuntimePageNode,
+  story: NonNullable<RuntimePageNode["stories"]["header" | "footer"]>,
+): PageLocalFieldLedger | undefined {
+  const pageLocalStory = page.frame?.pageLocalStories.find(
+    (candidate) =>
+      candidate.kind === story.kind &&
+      candidate.relationshipId === story.relationshipId &&
+      candidate.variant === story.variant &&
+      (story.sectionIndex === undefined ||
+        candidate.sectionIndex === story.sectionIndex),
+  );
+  return pageLocalStory?.resolvedFields;
+}
+
 function flattenBlocksToPreview(
   blocks: ReadonlyArray<BlockNode>,
   page: RuntimePageNode,
   graph: RuntimePageGraph,
+  fieldState: PagePreviewFieldState,
 ): string {
   const parts: string[] = [];
   for (const block of blocks) {
-    collectBlockText(block, page, graph, parts);
+    collectBlockText(block, page, graph, fieldState, parts);
     if (joinPreview(parts).length >= MAX_PREVIEW_CHARS) break;
   }
   return truncate(joinPreview(parts));
@@ -93,26 +125,27 @@ function collectBlockText(
   block: BlockNode,
   page: RuntimePageNode,
   graph: RuntimePageGraph,
+  fieldState: PagePreviewFieldState,
   out: string[],
 ): void {
   switch (block.type) {
     case "paragraph":
       for (const child of block.children) {
-        collectInlineText(child, page, graph, out);
+        collectInlineText(child, page, graph, fieldState, out);
       }
       break;
     case "table":
       for (const row of block.rows) {
         for (const cell of row.cells) {
           for (const childBlock of cell.children) {
-            collectBlockText(childBlock, page, graph, out);
+            collectBlockText(childBlock, page, graph, fieldState, out);
           }
         }
       }
       break;
     case "sdt":
       for (const child of block.children) {
-        collectBlockText(child, page, graph, out);
+        collectBlockText(child, page, graph, fieldState, out);
       }
       break;
     // opaque_block / section_break / custom_xml / alt_chunk — no preview text.
@@ -125,6 +158,7 @@ function collectInlineText(
   inline: InlineNode,
   page: RuntimePageNode,
   graph: RuntimePageGraph,
+  fieldState: PagePreviewFieldState,
   out: string[],
 ): void {
   switch (inline.type) {
@@ -141,8 +175,12 @@ function collectInlineText(
       const family = inline.fieldFamily ?? classifyFieldInstructionLocal(inline.instruction);
       const cached = flattenInline(inline.children);
       if (family === "PAGE" || family === "NUMPAGES" || family === "SECTIONPAGES") {
+        const ledgerField = fieldState.ledger?.[fieldState.ordinal];
+        fieldState.ordinal += 1;
         out.push(
-          resolvePageFieldDisplayText(family, cached, { page, graph }),
+          ledgerField?.family === family
+            ? ledgerField.displayText
+            : resolvePageFieldDisplayText(family, cached, { page, graph }),
         );
       } else {
         out.push(cached);
@@ -151,7 +189,7 @@ function collectInlineText(
     }
     case "hyperlink":
       for (const child of inline.children) {
-        collectInlineText(child, page, graph, out);
+        collectInlineText(child, page, graph, fieldState, out);
       }
       break;
     // bookmark_start/end, opaque_inline, note_ref etc — skip.

package/src/runtime/scopes/adjacent-geometry-evidence.ts

@@ -0,0 +1,456 @@
+/**
+ * Bounded adjacent geometry evidence from Layer 05.
+ *
+ * L08 consumes only compositor-ready `frame-px` rows from the L05 adjacent
+ * geometry intake. This evidence is read-side scope-bundle context; it is not
+ * replacement-envelope geometry and must not widen mutation capability.
+ */
+
+import type { FieldEnumeratedScope, EnumeratedScope } from "./enumerate-scopes.ts";
+import type {
+  ScopeAdjacentGeometryEvidence,
+  ScopeAdjacentGeometryFramePixelPoint,
+  ScopeAdjacentGeometryFramePixelRect,
+  ScopeAdjacentGeometryRowEvidence,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+interface FramePixelScaleLike {
+  readonly source?: unknown;
+  readonly renderFrameRevision?: unknown;
+}
+
+interface FramePixelProjectionLike {
+  readonly status?: unknown;
+  readonly coordinateSpace?: unknown;
+  readonly precision?: unknown;
+  readonly pageIndex?: unknown;
+  readonly pageId?: unknown;
+  readonly frameId?: unknown;
+  readonly scale?: FramePixelScaleLike;
+  readonly markerLane?: unknown;
+  readonly textColumn?: unknown;
+  readonly fieldStartAnchorPx?: unknown;
+  readonly fieldEndAnchorPx?: unknown;
+  readonly fieldResultRangePx?: unknown;
+}
+
+interface AdjacentPageLocalGeometryLike {
+  readonly compositorReady?: unknown;
+  readonly framePixelProjection?: FramePixelProjectionLike;
+}
+
+interface AdjacentNumberingRowLike {
+  readonly docId?: unknown;
+  readonly canonicalBlockId?: unknown;
+  readonly runtimeBlockId?: unknown;
+  readonly runtimeFragmentId?: unknown;
+  readonly runtimeNumberingId?: unknown;
+  readonly canonicalNumberingInstanceId?: unknown;
+  readonly canonicalLevel?: unknown;
+  readonly markerKind?: unknown;
+  readonly markerSuffix?: unknown;
+  readonly pageLocalGeometry?: AdjacentPageLocalGeometryLike;
+  readonly compositorReady?: unknown;
+}
+
+interface AdjacentFieldRegionRowLike {
+  readonly docId?: unknown;
+  readonly canonicalBlockId?: unknown;
+  readonly canonicalFieldId?: unknown;
+  readonly runtimeFieldRegionId?: unknown;
+  readonly runtimeFragmentId?: unknown;
+  readonly instructionFamily?: unknown;
+  readonly pageLocalGeometry?: AdjacentPageLocalGeometryLike;
+  readonly compositorReady?: unknown;
+}
+
+export interface AdjacentGeometryIntakeLike {
+  readonly schemaVersion?: unknown;
+  readonly pageLocalNormalization?: {
+    readonly framePixelCoordinateSpace?: unknown;
+    readonly compositorReady?: unknown;
+  };
+  readonly numberingRows?: readonly AdjacentNumberingRowLike[];
+  readonly fieldRegionRows?: readonly AdjacentFieldRegionRowLike[];
+}
+
+export interface ScopeAdjacentGeometryEvidenceProvider {
+  getScopeAdjacentGeometryEvidence(
+    scope: SemanticScope,
+    entry: EnumeratedScope | null,
+  ): ScopeAdjacentGeometryEvidence | null;
+}
+
+export interface ScopeAdjacentGeometryIntakeSummary {
+  readonly schemaVersion: string | null;
+  readonly intakeReady: boolean;
+  readonly numberingCompositorReadyRows: number;
+  readonly fieldRegionCompositorReadyRows: number;
+  readonly eligibleRowCount: number;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function parseParagraphBlockIndex(value: unknown): number | undefined {
+  const raw = stringValue(value);
+  if (!raw) return undefined;
+  const match = /^paragraph-(\d+)$/.exec(raw);
+  return match ? Number(match[1]) : undefined;
+}
+
+function docMatches(scope: SemanticScope, docId: string | undefined): boolean {
+  return !docId || !scope.handle.documentId || scope.handle.documentId === docId;
+}
+
+function isCompositorReady(geometry: AdjacentPageLocalGeometryLike | undefined): boolean {
+  const projection = geometry?.framePixelProjection;
+  return (
+    geometry?.compositorReady === true &&
+    projection?.status === "projected-frame-pixels" &&
+    projection.coordinateSpace === "frame-px" &&
+    projection.precision === "word-page-local-calibration"
+  );
+}
+
+function normalizeRect(value: unknown): ScopeAdjacentGeometryFramePixelRect | undefined {
+  const rect = value as
+    | {
+        readonly leftPx?: unknown;
+        readonly topPx?: unknown;
+        readonly widthPx?: unknown;
+        readonly heightPx?: unknown;
+        readonly coordinateSpace?: unknown;
+      }
+    | undefined;
+  const leftPx = numberValue(rect?.leftPx);
+  const topPx = numberValue(rect?.topPx);
+  const widthPx = numberValue(rect?.widthPx);
+  const heightPx = numberValue(rect?.heightPx);
+  if (
+    leftPx === undefined ||
+    topPx === undefined ||
+    widthPx === undefined ||
+    heightPx === undefined ||
+    rect?.coordinateSpace !== "frame-px"
+  ) {
+    return undefined;
+  }
+  return { leftPx, topPx, widthPx, heightPx, coordinateSpace: "frame-px" };
+}
+
+function normalizePoint(value: unknown): ScopeAdjacentGeometryFramePixelPoint | undefined {
+  const point = value as
+    | {
+        readonly xPx?: unknown;
+        readonly yPx?: unknown;
+        readonly coordinateSpace?: unknown;
+      }
+    | undefined;
+  const xPx = numberValue(point?.xPx);
+  const yPx = numberValue(point?.yPx);
+  if (xPx === undefined || yPx === undefined || point?.coordinateSpace !== "frame-px") {
+    return undefined;
+  }
+  return { xPx, yPx, coordinateSpace: "frame-px" };
+}
+
+function baseRow(
+  axis: ScopeAdjacentGeometryRowEvidence["axis"],
+  input: {
+    readonly docId?: string;
+    readonly canonicalBlockId?: string;
+    readonly runtimeFragmentId?: string;
+    readonly projection: FramePixelProjectionLike;
+  },
+): Omit<ScopeAdjacentGeometryRowEvidence, "numbering" | "fieldRegion"> {
+  return {
+    axis,
+    source: "l05-adjacent-geometry-intake",
+    ...(input.docId ? { docId: input.docId } : {}),
+    ...(input.canonicalBlockId ? { canonicalBlockId: input.canonicalBlockId } : {}),
+    ...(input.runtimeFragmentId ? { runtimeFragmentId: input.runtimeFragmentId } : {}),
+    ...(typeof input.projection.pageId === "string"
+      ? { pageId: input.projection.pageId }
+      : {}),
+    ...(typeof input.projection.frameId === "string"
+      ? { frameId: input.projection.frameId }
+      : {}),
+    ...(numberValue(input.projection.pageIndex) !== undefined
+      ? { pageIndex: numberValue(input.projection.pageIndex) }
+      : {}),
+    precision: "word-page-local-calibration",
+    coordinateSpace: "frame-px",
+    compositorReady: true,
+    ...(input.projection.scale?.source === "runtime-render-frame-page-rect"
+      ? { scaleSource: "runtime-render-frame-page-rect" as const }
+      : {}),
+    ...(numberValue(input.projection.scale?.renderFrameRevision) !== undefined
+      ? { renderFrameRevision: numberValue(input.projection.scale?.renderFrameRevision) }
+      : {}),
+  };
+}
+
+function projectNumberingRow(row: AdjacentNumberingRowLike): ScopeAdjacentGeometryRowEvidence | null {
+  if (row.compositorReady !== true || !isCompositorReady(row.pageLocalGeometry)) return null;
+  const projection = row.pageLocalGeometry!.framePixelProjection!;
+  const docId = stringValue(row.docId);
+  const canonicalBlockId = stringValue(row.canonicalBlockId) ?? stringValue(row.runtimeBlockId);
+  return {
+    ...baseRow("numbering-marker", {
+      docId,
+      canonicalBlockId,
+      runtimeFragmentId: stringValue(row.runtimeFragmentId),
+      projection,
+    }),
+    numbering: {
+      ...(stringValue(row.runtimeNumberingId)
+        ? { runtimeNumberingId: stringValue(row.runtimeNumberingId) }
+        : {}),
+      ...(stringValue(row.canonicalNumberingInstanceId)
+        ? { canonicalNumberingInstanceId: stringValue(row.canonicalNumberingInstanceId) }
+        : {}),
+      ...(numberValue(row.canonicalLevel) !== undefined
+        ? { canonicalLevel: numberValue(row.canonicalLevel) }
+        : {}),
+      ...(stringValue(row.markerKind) ? { markerKind: stringValue(row.markerKind) } : {}),
+      ...(stringValue(row.markerSuffix) ? { markerSuffix: stringValue(row.markerSuffix) } : {}),
+      ...(normalizeRect(projection.markerLane)
+        ? { markerLane: normalizeRect(projection.markerLane) }
+        : {}),
+      ...(normalizeRect(projection.textColumn)
+        ? { textColumn: normalizeRect(projection.textColumn) }
+        : {}),
+    },
+  };
+}
+
+function projectFieldRegionRow(
+  row: AdjacentFieldRegionRowLike,
+): ScopeAdjacentGeometryRowEvidence | null {
+  if (row.compositorReady !== true || !isCompositorReady(row.pageLocalGeometry)) return null;
+  const projection = row.pageLocalGeometry!.framePixelProjection!;
+  const docId = stringValue(row.docId);
+  const canonicalBlockId = stringValue(row.canonicalBlockId);
+  return {
+    ...baseRow("field-region", {
+      docId,
+      canonicalBlockId,
+      runtimeFragmentId: stringValue(row.runtimeFragmentId),
+      projection,
+    }),
+    fieldRegion: {
+      ...(stringValue(row.canonicalFieldId)
+        ? { canonicalFieldId: stringValue(row.canonicalFieldId) }
+        : {}),
+      ...(stringValue(row.runtimeFieldRegionId)
+        ? { runtimeFieldRegionId: stringValue(row.runtimeFieldRegionId) }
+        : {}),
+      ...(stringValue(row.instructionFamily)
+        ? { instructionFamily: stringValue(row.instructionFamily) }
+        : {}),
+      ...(normalizePoint(projection.fieldStartAnchorPx)
+        ? { fieldStartAnchorPx: normalizePoint(projection.fieldStartAnchorPx) }
+        : {}),
+      ...(normalizePoint(projection.fieldEndAnchorPx)
+        ? { fieldEndAnchorPx: normalizePoint(projection.fieldEndAnchorPx) }
+        : {}),
+      ...(normalizeRect(projection.fieldResultRangePx)
+        ? { fieldResultRangePx: normalizeRect(projection.fieldResultRangePx) }
+        : {}),
+    },
+  };
+}
+
+function numberingRowMatchesScope(
+  row: ScopeAdjacentGeometryRowEvidence,
+  scope: SemanticScope,
+  entry: EnumeratedScope | null,
+): boolean {
+  if (scope.kind !== "list-item" || entry?.kind !== "list-item") return false;
+  if (!docMatches(scope, row.docId)) return false;
+  const rowBlockIndex = parseParagraphBlockIndex(row.canonicalBlockId);
+  if (rowBlockIndex !== undefined && rowBlockIndex !== entry.blockIndex) return false;
+  const numbering = row.numbering;
+  if (
+    numbering?.canonicalNumberingInstanceId &&
+    scope.formatting.numbering?.numberingInstanceId &&
+    numbering.canonicalNumberingInstanceId !== scope.formatting.numbering.numberingInstanceId
+  ) {
+    return false;
+  }
+  if (
+    numbering?.canonicalLevel !== undefined &&
+    scope.formatting.numbering?.level !== undefined &&
+    numbering.canonicalLevel !== scope.formatting.numbering.level
+  ) {
+    return false;
+  }
+  return rowBlockIndex !== undefined;
+}
+
+function fieldRowMatchesScope(
+  row: ScopeAdjacentGeometryRowEvidence,
+  scope: SemanticScope,
+  entry: EnumeratedScope | null,
+): boolean {
+  if (scope.kind !== "field" || entry?.kind !== "field") return false;
+  if (!docMatches(scope, row.docId)) return false;
+  const fieldEntry = entry as FieldEnumeratedScope;
+  const rowCanonicalFieldId = row.fieldRegion?.canonicalFieldId;
+  if (rowCanonicalFieldId && fieldEntry.field.canonicalFieldId) {
+    return rowCanonicalFieldId === fieldEntry.field.canonicalFieldId;
+  }
+  const rowBlockIndex = parseParagraphBlockIndex(row.canonicalBlockId);
+  return rowBlockIndex !== undefined && rowBlockIndex === fieldEntry.blockIndex;
+}
+
+export function createAdjacentGeometryScopeEvidenceProvider(
+  intake: AdjacentGeometryIntakeLike,
+): ScopeAdjacentGeometryEvidenceProvider {
+  const intakeReady = isIntakeReady(intake);
+  const numberingRows = intakeReady
+    ? (intake.numberingRows ?? []).map(projectNumberingRow).filter(isEvidenceRow)
+    : [];
+  const fieldRegionRows = intakeReady
+    ? (intake.fieldRegionRows ?? []).map(projectFieldRegionRow).filter(isEvidenceRow)
+    : [];
+  const allRows = Object.freeze([...numberingRows, ...fieldRegionRows]);
+
+  return {
+    getScopeAdjacentGeometryEvidence(scope, entry) {
+      if (!intakeReady) {
+        return {
+          status: "unavailable",
+          source: "l05-adjacent-geometry-intake",
+          rowCount: 0,
+          reason: "l05-adjacent-intake-not-compositor-ready",
+        };
+      }
+      const rows = allRows.filter(
+        (row) =>
+          numberingRowMatchesScope(row, scope, entry) ||
+          fieldRowMatchesScope(row, scope, entry),
+      );
+      if (rows.length === 0) return null;
+      return {
+        status: "available",
+        source: "l05-adjacent-geometry-intake",
+        schemaVersion: "layer-05-adjacent-geometry-intake/v2",
+        rowCount: rows.length,
+        rows: Object.freeze(rows.map(cloneAdjacentGeometryRow)),
+      };
+    },
+  };
+}
+
+export function summarizeAdjacentGeometryEvidenceIntake(
+  intake: AdjacentGeometryIntakeLike,
+): ScopeAdjacentGeometryIntakeSummary {
+  const intakeReady = isIntakeReady(intake);
+  const numberingCompositorReadyRows = intakeReady
+    ? (intake.numberingRows ?? []).map(projectNumberingRow).filter(isEvidenceRow).length
+    : 0;
+  const fieldRegionCompositorReadyRows = intakeReady
+    ? (intake.fieldRegionRows ?? []).map(projectFieldRegionRow).filter(isEvidenceRow).length
+    : 0;
+  return {
+    schemaVersion: typeof intake.schemaVersion === "string" ? intake.schemaVersion : null,
+    intakeReady,
+    numberingCompositorReadyRows,
+    fieldRegionCompositorReadyRows,
+    eligibleRowCount: numberingCompositorReadyRows + fieldRegionCompositorReadyRows,
+  };
+}
+
+function isIntakeReady(intake: AdjacentGeometryIntakeLike): boolean {
+  return (
+    intake.schemaVersion === "layer-05-adjacent-geometry-intake/v2" &&
+    intake.pageLocalNormalization?.framePixelCoordinateSpace === "frame-px" &&
+    intake.pageLocalNormalization.compositorReady === true
+  );
+}
+
+function isEvidenceRow(
+  row: ScopeAdjacentGeometryRowEvidence | null,
+): row is ScopeAdjacentGeometryRowEvidence {
+  return row !== null;
+}
+
+function cloneRect(
+  rect: ScopeAdjacentGeometryFramePixelRect | undefined,
+): ScopeAdjacentGeometryFramePixelRect | undefined {
+  return rect ? { ...rect } : undefined;
+}
+
+function clonePoint(
+  point: ScopeAdjacentGeometryFramePixelPoint | undefined,
+): ScopeAdjacentGeometryFramePixelPoint | undefined {
+  return point ? { ...point } : undefined;
+}
+
+function cloneAdjacentGeometryRow(
+  row: ScopeAdjacentGeometryRowEvidence,
+): ScopeAdjacentGeometryRowEvidence {
+  return {
+    ...row,
+    ...(row.numbering
+      ? {
+          numbering: {
+            ...row.numbering,
+            ...(row.numbering.markerLane
+              ? { markerLane: cloneRect(row.numbering.markerLane) }
+              : {}),
+            ...(row.numbering.textColumn
+              ? { textColumn: cloneRect(row.numbering.textColumn) }
+              : {}),
+          },
+        }
+      : {}),
+    ...(row.fieldRegion
+      ? {
+          fieldRegion: {
+            ...row.fieldRegion,
+            ...(row.fieldRegion.fieldStartAnchorPx
+              ? { fieldStartAnchorPx: clonePoint(row.fieldRegion.fieldStartAnchorPx) }
+              : {}),
+            ...(row.fieldRegion.fieldEndAnchorPx
+              ? { fieldEndAnchorPx: clonePoint(row.fieldRegion.fieldEndAnchorPx) }
+              : {}),
+            ...(row.fieldRegion.fieldResultRangePx
+              ? { fieldResultRangePx: cloneRect(row.fieldRegion.fieldResultRangePx) }
+              : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+export function deriveScopeAdjacentGeometryEvidence(
+  scope: SemanticScope,
+  entry: EnumeratedScope | null,
+  provider?: ScopeAdjacentGeometryEvidenceProvider,
+): ScopeAdjacentGeometryEvidence | undefined {
+  if (!provider) return undefined;
+  const evidence = provider.getScopeAdjacentGeometryEvidence(scope, entry);
+  if (!evidence) {
+    return {
+      status: "unavailable",
+      source: "l05-adjacent-geometry-intake",
+      rowCount: 0,
+      reason: "scope-adjacent-frame-pixel-row-unavailable",
+    };
+  }
+  return {
+    ...evidence,
+    ...(evidence.rows
+      ? { rows: Object.freeze(evidence.rows.map(cloneAdjacentGeometryRow)) }
+      : {}),
+  };
+}

package/src/runtime/scopes/compile-scope-bundle.ts

@@ -18,6 +18,7 @@ import type {
   WorkflowOverlay,
 } from "./_scope-dependencies.ts";
 import type { ScopeGeometryEvidenceProvider } from "./geometry-evidence.ts";
+import type { ScopeAdjacentGeometryEvidenceProvider } from "./adjacent-geometry-evidence.ts";
 
 import {
   buildParagraphIndexMap,
@@ -59,6 +60,12 @@ export interface ScopeBundleInputs {
    * records layout as unavailable instead of deriving page slices in L08.
    */
   readonly layout?: ScopeLayoutEvidenceProvider;
+  /**
+   * Optional Layer-05 adjacent geometry intake seam for compositor-ready
+   * `frame-px` rows. Kept separate from replacement-envelope geometry so it
+   * cannot widen edit capability.
+   */
+  readonly adjacentGeometry?: ScopeAdjacentGeometryEvidenceProvider;
 }
 
 /**
@@ -140,6 +147,7 @@ export function compileScopeBundle(
       : {}),
     ...(inputs.geometry ? { geometry: inputs.geometry } : {}),
     ...(inputs.layout ? { layout: inputs.layout } : {}),
+    ...(inputs.adjacentGeometry ? { adjacentGeometry: inputs.adjacentGeometry } : {}),
   });
   return {
     scope,

package/src/runtime/scopes/evidence.ts

@@ -24,6 +24,10 @@ import type {
 } from "./_scope-dependencies.ts";
 
 import { AI_EXPLANATION_METADATA_ID } from "./attach-explanation.ts";
+import {
+  deriveScopeAdjacentGeometryEvidence,
+  type ScopeAdjacentGeometryEvidenceProvider,
+} from "./adjacent-geometry-evidence.ts";
 import { deriveScopeCapabilities } from "./capabilities.ts";
 import { deriveScopeContentControlEvidence } from "./content-control-evidence.ts";
 import { AI_ISSUE_METADATA_ID } from "./create-issue.ts";
@@ -107,6 +111,12 @@ export interface EvidenceInputs {
    * rows are surfaced explicitly in `ScopeBundleEvidence.layout`.
    */
   readonly layout?: ScopeLayoutEvidenceProvider;
+  /**
+   * Optional Layer-05 adjacent geometry intake seam. This is bounded
+   * compositor/read evidence and does not participate in replacement
+   * capability derivation.
+   */
+  readonly adjacentGeometry?: ScopeAdjacentGeometryEvidenceProvider;
 }
 
 function normalizeSeverity(raw: unknown): AIIssueSummary["severity"] {
@@ -301,6 +311,11 @@ export function composeEvidence(inputs: EvidenceInputs): ScopeBundleEvidence {
 
   const layout = deriveScopeLayoutEvidence(scope.handle.scopeId, inputs.layout);
   const geometry = deriveScopeGeometryEvidence(scope.handle.scopeId, inputs.geometry);
+  const adjacentGeometry = deriveScopeAdjacentGeometryEvidence(
+    scope,
+    entry,
+    inputs.adjacentGeometry,
+  );
   const contentControls = deriveScopeContentControlEvidence(document, selfRange);
 
   return {
@@ -310,6 +325,7 @@ export function composeEvidence(inputs: EvidenceInputs): ScopeBundleEvidence {
     compatibilityFlags,
     layout,
     geometry,
+    ...(adjacentGeometry ? { adjacentGeometry } : {}),
     visualization: deriveScopeVisualization(scope),
     contentControls,
     capabilities: deriveScopeCapabilities(scope, {

package/src/runtime/scopes/index.ts

@@ -52,6 +52,11 @@ export type {
   ScopeFormattingClearTarget,
   ScopeFormattingScope,
   ScopeActionPosture,
+  ScopeAdjacentGeometryAxis,
+  ScopeAdjacentGeometryEvidence,
+  ScopeAdjacentGeometryFramePixelPoint,
+  ScopeAdjacentGeometryFramePixelRect,
+  ScopeAdjacentGeometryRowEvidence,
   ScopeBundle,
   ScopeBundleEvidence,
   ScopeBundleNeighborhood,
@@ -73,6 +78,14 @@ export type {
   ValidationIssue,
   ValidationResult,
 } from "./semantic-scope-types.ts";
+export {
+  createAdjacentGeometryScopeEvidenceProvider,
+  deriveScopeAdjacentGeometryEvidence,
+  summarizeAdjacentGeometryEvidenceIntake,
+  type AdjacentGeometryIntakeLike,
+  type ScopeAdjacentGeometryIntakeSummary,
+  type ScopeAdjacentGeometryEvidenceProvider,
+} from "./adjacent-geometry-evidence.ts";
 export { deriveScopeCapabilities } from "./capabilities.ts";
 export type { ScopeCapabilityContext } from "./capabilities.ts";
 export {