@beyondwork/docx-react-component 1.0.108 → 1.0.110

package/src/runtime/geometry/adjacent-geometry-intake.ts

@@ -25,15 +25,60 @@ export interface AdjacentGeometryPageSpan {
   readonly endPage?: number | null;
 }
 
+export type AdjacentGeometryPageIndexStatus =
+  | "matches-runtime"
+  | "differs-from-runtime"
+  | "runtime-missing"
+  | "word-page-missing";
+
+export interface AdjacentGeometryL04FrameProjection {
+  readonly pageIndex?: number;
+  readonly pageId?: string;
+  readonly frameId?: string;
+  readonly frameCompleteness?: string;
+  readonly physicalBoundsTwips?: AdjacentGeometryTwipsRect;
+  readonly markerLane?: AdjacentGeometryTwipsRect;
+  readonly textColumn?: AdjacentGeometryTwipsRect;
+  readonly fieldStartAnchorTwips?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  readonly fieldEndAnchorTwips?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  readonly coordinateSpace: "l04-frame-twips";
+  readonly precision: "word-page-local-calibration";
+  readonly status:
+    | "projected-l04-frame"
+    | "page-index-differs-from-runtime"
+    | "runtime-page-missing"
+    | "word-page-missing"
+    | "missing-l04-page-frame"
+    | "missing-word-page-local-geometry";
+}
+
+interface AdjacentGeometryPageFrame {
+  readonly pageId?: string;
+  readonly pageIndex: number;
+  readonly frameId?: string;
+  readonly completeness?: string;
+  readonly physicalBoundsTwips?: AdjacentGeometryTwipsRect;
+}
+
 export interface AdjacentGeometryPageLocalNumberingGeometry {
   readonly wordPage?: number;
+  readonly normalizedWordPageIndex?: number;
   readonly runtimePageIndex?: number;
+  readonly pageIndexStatus: AdjacentGeometryPageIndexStatus;
   readonly runtimeFragmentId?: string;
   readonly markerLane?: AdjacentGeometryTwipsRect;
   readonly textColumn?: AdjacentGeometryTwipsRect;
+  readonly l04FrameProjection: AdjacentGeometryL04FrameProjection;
   readonly coordinateSpace: "word-page-twips";
   readonly precision: "word-page-local-calibration";
   readonly normalizationStatus:
+    | "l04-frame-twips-projected"
     | "word-page-local-awaiting-l04-frame-projection"
     | "missing-word-page-local-lane";
 }
@@ -56,9 +101,11 @@ export interface AdjacentGeometryPageLocalFieldGeometry {
     readonly x?: number;
     readonly y?: number;
   };
+  readonly l04FrameProjection: AdjacentGeometryL04FrameProjection;
   readonly coordinateSpace: "word-page-twips";
   readonly precision: "word-page-local-calibration";
   readonly normalizationStatus:
+    | "l04-frame-twips-projected"
     | "word-page-local-awaiting-l04-frame-projection"
     | "missing-word-placement";
 }
@@ -69,6 +116,9 @@ export interface AdjacentGeometryNumberingRowSummary {
   readonly canonicalBlockId?: string;
   readonly runtimeBlockId?: string;
   readonly runtimeFragmentId?: string;
+  readonly runtimeNumberingId?: string;
+  readonly layoutObjectId?: string;
+  readonly runtimeJoinSource: "adjacent-live" | "l04-numbering-readback";
   readonly runtimePageIndex?: number;
   readonly sourceParagraphPath?: string;
   readonly canonicalNumberingInstanceId?: string;
@@ -141,6 +191,7 @@ export interface AdjacentGeometryDocumentSummary {
   readonly docId: string;
   readonly numberingRows: number;
   readonly numberingRowsWithRuntimeFragment: number;
+  readonly numberingRowsJoinedFromL04Readback: number;
   readonly numberingParagraphLineRects: number;
   readonly numberingTextOnlyLineRects: number;
   readonly numberingRawMarkerRectRows: number;
@@ -150,6 +201,10 @@ export interface AdjacentGeometryDocumentSummary {
   readonly numberingRowsWithUiaCapture: number;
   readonly numberingRowsWithPageLocalMarkerLane: number;
   readonly numberingRowsWithPageLocalTextColumn: number;
+  readonly numberingRowsWithRuntimePageMatch: number;
+  readonly numberingUiaRowsWithRuntimePageMatch: number;
+  readonly numberingRowsWithL04FrameProjection: number;
+  readonly numberingUiaRowsWithL04FrameProjection: number;
   readonly fieldRegionRows: number;
   readonly fieldRegionRowsWithRuntimeId: number;
   readonly fieldRegionResultLineRects: number;
@@ -157,10 +212,12 @@ export interface AdjacentGeometryDocumentSummary {
   readonly fieldRegionRowsWithWordPlacement: number;
   readonly fieldRegionRowsWithRuntimePageMatch: number;
   readonly fieldRegionRowsWithRuntimePageContainment: number;
+  readonly fieldRegionRowsWithL04FrameProjection: number;
+  readonly fieldRegionUiaRowsWithL04FrameProjection: number;
 }
 
 export interface AdjacentGeometryIntakeSummary {
-  readonly schemaVersion: "layer-05-adjacent-geometry-intake/v0";
+  readonly schemaVersion: "layer-05-adjacent-geometry-intake/v1";
   readonly generatedAtUtc: string;
   readonly sourceRuns: {
     readonly adjacentLiveWordJoins: string;
@@ -170,6 +227,7 @@ export interface AdjacentGeometryIntakeSummary {
   readonly totals: {
     readonly numberingRows: number;
     readonly numberingRowsWithRuntimeFragment: number;
+    readonly numberingRowsJoinedFromL04Readback: number;
     readonly numberingParagraphLineRects: number;
     readonly numberingTextOnlyLineRects: number;
     readonly numberingRawMarkerRectRows: number;
@@ -179,6 +237,10 @@ export interface AdjacentGeometryIntakeSummary {
     readonly numberingRowsWithUiaCapture: number;
     readonly numberingRowsWithPageLocalMarkerLane: number;
     readonly numberingRowsWithPageLocalTextColumn: number;
+    readonly numberingRowsWithRuntimePageMatch: number;
+    readonly numberingUiaRowsWithRuntimePageMatch: number;
+    readonly numberingRowsWithL04FrameProjection: number;
+    readonly numberingUiaRowsWithL04FrameProjection: number;
     readonly fieldRegionRows: number;
     readonly fieldRegionRowsWithRuntimeId: number;
     readonly fieldRegionResultLineRects: number;
@@ -186,6 +248,8 @@ export interface AdjacentGeometryIntakeSummary {
     readonly fieldRegionRowsWithWordPlacement: number;
     readonly fieldRegionRowsWithRuntimePageMatch: number;
     readonly fieldRegionRowsWithRuntimePageContainment: number;
+    readonly fieldRegionRowsWithL04FrameProjection: number;
+    readonly fieldRegionUiaRowsWithL04FrameProjection: number;
   };
   readonly routing: {
     readonly routedTo: "L05";
@@ -198,6 +262,8 @@ export interface AdjacentGeometryIntakeSummary {
     readonly coordinateSpace: "word-page-twips";
     readonly precision: "word-page-local-calibration";
     readonly requiredUpstreamFact: "L04 frame-to-pixel projection";
+    readonly l04FrameProjectionCoordinateSpace: "l04-frame-twips";
+    readonly l04FrameProjectionPrecision: "word-page-local-calibration";
     readonly compositorReady: false;
   };
   readonly documents: readonly AdjacentGeometryDocumentSummary[];
@@ -210,16 +276,23 @@ export function summarizeAdjacentGeometryIntake(input: {
   readonly sourceRuns: AdjacentGeometryIntakeSummary["sourceRuns"];
   readonly numberingArtifact: unknown;
   readonly numberingLiveJoinArtifacts: readonly unknown[];
+  readonly numberingRuntimeReadbackArtifacts?: readonly unknown[];
   readonly fieldRegionRuntimeReadback: unknown;
   readonly fieldRegionLiveJoinArtifacts: readonly unknown[];
 }): AdjacentGeometryIntakeSummary {
+  const pageFramesByDocId = collectPageFramesByDocId(
+    input.numberingRuntimeReadbackArtifacts ?? [],
+  );
   const numberingRows = summarizeNumberingRows(
     input.numberingArtifact,
     input.numberingLiveJoinArtifacts,
+    input.numberingRuntimeReadbackArtifacts ?? [],
+    pageFramesByDocId,
   );
   const fieldRegionRows = summarizeFieldRegionRows(
     input.fieldRegionRuntimeReadback,
     input.fieldRegionLiveJoinArtifacts,
+    pageFramesByDocId,
   );
   const docIds = [
     ...new Set([
@@ -228,7 +301,7 @@ export function summarizeAdjacentGeometryIntake(input: {
     ]),
   ].sort();
   return {
-    schemaVersion: "layer-05-adjacent-geometry-intake/v0",
+    schemaVersion: "layer-05-adjacent-geometry-intake/v1",
     generatedAtUtc: input.generatedAtUtc,
     sourceRuns: input.sourceRuns,
     totals: {
@@ -236,6 +309,9 @@ export function summarizeAdjacentGeometryIntake(input: {
       numberingRowsWithRuntimeFragment: numberingRows.filter(
         (row) => row.runtimeFragmentId !== undefined,
       ).length,
+      numberingRowsJoinedFromL04Readback: numberingRows.filter(
+        (row) => row.runtimeJoinSource === "l04-numbering-readback",
+      ).length,
       numberingParagraphLineRects: sum(
         numberingRows,
         (row) => row.paragraphLineRectCount,
@@ -258,6 +334,19 @@ export function summarizeAdjacentGeometryIntake(input: {
       numberingRowsWithPageLocalTextColumn: numberingRows.filter(
         (row) => row.pageLocalGeometry.textColumn !== undefined,
       ).length,
+      numberingRowsWithRuntimePageMatch: numberingRows.filter(
+        (row) => row.pageLocalGeometry.pageIndexStatus === "matches-runtime",
+      ).length,
+      numberingUiaRowsWithRuntimePageMatch: numberingRows.filter(
+        (row) =>
+          hasNumberingUiaCapture(row) &&
+          row.pageLocalGeometry.pageIndexStatus === "matches-runtime",
+      ).length,
+      numberingRowsWithL04FrameProjection: numberingRows.filter(hasL04FrameProjection)
+        .length,
+      numberingUiaRowsWithL04FrameProjection: numberingRows.filter(
+        (row) => hasNumberingUiaCapture(row) && hasL04FrameProjection(row),
+      ).length,
       fieldRegionRows: fieldRegionRows.length,
       fieldRegionRowsWithRuntimeId: fieldRegionRows.filter(
         (row) => row.runtimeFieldRegionId !== undefined,
@@ -278,6 +367,12 @@ export function summarizeAdjacentGeometryIntake(input: {
       fieldRegionRowsWithRuntimePageContainment: fieldRegionRows.filter(
         (row) => row.pageLocalGeometry.pageSpanStatus === "contained-in-runtime",
       ).length,
+      fieldRegionRowsWithL04FrameProjection: fieldRegionRows.filter(
+        hasL04FrameProjection,
+      ).length,
+      fieldRegionUiaRowsWithL04FrameProjection: fieldRegionRows.filter(
+        (row) => row.resultLineRectCount > 0 && hasL04FrameProjection(row),
+      ).length,
     },
     routing: {
       routedTo: "L05",
@@ -290,6 +385,8 @@ export function summarizeAdjacentGeometryIntake(input: {
       coordinateSpace: "word-page-twips",
       precision: "word-page-local-calibration",
       requiredUpstreamFact: "L04 frame-to-pixel projection",
+      l04FrameProjectionCoordinateSpace: "l04-frame-twips",
+      l04FrameProjectionPrecision: "word-page-local-calibration",
       compositorReady: false,
     },
     documents: docIds.map((docId) =>
@@ -307,6 +404,8 @@ export function summarizeAdjacentGeometryIntake(input: {
 function summarizeNumberingRows(
   artifact: unknown,
   liveJoinArtifacts: readonly unknown[],
+  runtimeReadbackArtifacts: readonly unknown[],
+  pageFramesByDocId: ReadonlyMap<string, ReadonlyMap<number, AdjacentGeometryPageFrame>>,
 ): readonly AdjacentGeometryNumberingRowSummary[] {
   const uiaRowsByKey = new Map<string, Record<string, unknown>>();
   for (const raw of array(record(artifact).rows)) {
@@ -322,8 +421,16 @@ function summarizeNumberingRows(
   const liveRows = liveJoinArtifacts.flatMap((artifact) =>
     array(record(artifact).numberingRows).map(record),
   );
+  const runtimeReadbacksByKey = collectNumberingRuntimeReadbacks(
+    runtimeReadbackArtifacts,
+  );
   const rows = liveRows.length > 0
-    ? liveRows.filter((row) => stringValue(row.runtimeFragmentId) !== undefined)
+    ? liveRows.filter((row) => {
+        if (stringValue(row.runtimeFragmentId) !== undefined) return true;
+        return (
+          numberingRuntimeReadbackForRow(row, runtimeReadbacksByKey) !== undefined
+        );
+      })
     : array(record(artifact).rows).map(record);
 
   return rows
@@ -338,6 +445,10 @@ function summarizeNumberingRows(
       const uiaRow =
         uiaRowsByKey.get(numberingKey(docId, wordParagraphOrdinalGlobal) ?? "") ??
         {};
+      const runtimeReadback = numberingRuntimeReadbackForRow(
+        row,
+        runtimeReadbacksByKey,
+      );
       const uiaTargetJoin = record(uiaRow.targetJoin);
       const paragraphLineRects = chooseRects(
         uiaRow.paragraphLineRects,
@@ -350,28 +461,60 @@ function summarizeNumberingRows(
       const rawMarkerRects = chooseRawArray(uiaRow.markerRects, row.markerRects);
       const markerRects = chooseRects(uiaRow.markerRects, row.markerRects);
       const markerLane =
-        normalizeTwipsRect(row.markerLane) ?? normalizeTwipsRect(uiaTargetJoin.markerLane);
+        normalizeTwipsRect(row.markerLane) ??
+        normalizeTwipsRect(runtimeReadback?.markerLane) ??
+        normalizeTwipsRect(uiaTargetJoin.markerLane);
       const textColumn =
-        normalizeTwipsRect(row.textColumn) ?? normalizeTwipsRect(uiaTargetJoin.textColumn);
+        normalizeTwipsRect(row.textColumn) ??
+        normalizeTwipsRect(runtimeReadback?.textColumn) ??
+        normalizeTwipsRect(uiaTargetJoin.textColumn);
       const runtimeFragmentId =
-        stringValue(row.runtimeFragmentId) ?? stringValue(uiaTargetJoin.runtimeFragmentId);
+        stringValue(row.runtimeFragmentId) ??
+        stringValue(runtimeReadback?.runtimeFragmentId) ??
+        stringValue(uiaTargetJoin.runtimeFragmentId);
+      const runtimeJoinSource: AdjacentGeometryNumberingRowSummary["runtimeJoinSource"] =
+        stringValue(row.runtimeFragmentId) !== undefined
+          ? "adjacent-live"
+          : "l04-numbering-readback";
       const runtimePageIndex =
-        numberValue(row.runtimePageIndex) ?? numberValue(uiaTargetJoin.runtimePageIndex);
+        numberValue(row.runtimePageIndex) ??
+        numberValue(runtimeReadback?.pageIndex) ??
+        numberValue(uiaTargetJoin.runtimePageIndex);
       const wordStartPage =
         numberValue(record(row.pageSpan).startPage) ??
         numberValue(row.wordStartPage) ??
         numberValue(uiaRow.wordStartPage);
+      const normalizedWordPageIndex =
+        wordStartPage === undefined ? undefined : wordStartPage - 1;
+      const pageIndexStatus = classifyPageIndex(
+        normalizedWordPageIndex,
+        runtimePageIndex,
+      );
+      const l04FrameProjection = projectNumberingToL04Frame({
+        docId,
+        normalizedWordPageIndex,
+        runtimePageIndex,
+        pageIndexStatus,
+        markerLane,
+        textColumn,
+        pageFramesByDocId,
+      });
       const pageLocalGeometry: AdjacentGeometryPageLocalNumberingGeometry = {
         wordPage: wordStartPage,
+        normalizedWordPageIndex,
         runtimePageIndex,
+        pageIndexStatus,
         runtimeFragmentId,
         markerLane,
         textColumn,
+        l04FrameProjection,
         coordinateSpace: "word-page-twips",
         precision: "word-page-local-calibration",
         normalizationStatus:
-          markerLane || textColumn
-            ? "word-page-local-awaiting-l04-frame-projection"
+          l04FrameProjection.status === "projected-l04-frame"
+            ? "l04-frame-twips-projected"
+            : markerLane || textColumn
+              ? "word-page-local-awaiting-l04-frame-projection"
             : "missing-word-page-local-lane",
       };
       return {
@@ -380,11 +523,20 @@ function summarizeNumberingRows(
         canonicalBlockId:
           stringValue(row.canonicalBlockId) ?? stringValue(uiaTargetJoin.canonicalBlockId),
         runtimeBlockId:
-          stringValue(row.runtimeBlockId) ?? stringValue(uiaTargetJoin.runtimeBlockId),
+          stringValue(row.runtimeBlockId) ??
+          stringValue(runtimeReadback?.numberingSourceBlockId) ??
+          stringValue(runtimeReadback?.sourceBlockId) ??
+          stringValue(uiaTargetJoin.runtimeBlockId),
         runtimeFragmentId,
+        runtimeNumberingId:
+          stringValue(runtimeReadback?.runtimeNumberingId) ??
+          stringValue(record(row.runtimeJoinAttempt).runtimeNumberingId),
+        layoutObjectId: stringValue(runtimeReadback?.layoutObjectId),
+        runtimeJoinSource,
         runtimePageIndex,
         sourceParagraphPath:
           stringValue(row.sourceParagraphPath) ??
+          stringValue(runtimeReadback?.sourceBlockPath) ??
           stringValue(uiaTargetJoin.sourceParagraphPath),
         canonicalNumberingInstanceId:
           stringValue(row.canonicalNumberingInstanceId) ??
@@ -423,6 +575,7 @@ function summarizeNumberingRows(
 function summarizeFieldRegionRows(
   runtimeReadback: unknown,
   liveJoinArtifacts: readonly unknown[],
+  pageFramesByDocId: ReadonlyMap<string, ReadonlyMap<number, AdjacentGeometryPageFrame>>,
 ): readonly AdjacentGeometryFieldRegionRowSummary[] {
   const liveJoinByOrdinalKey = new Map<string, Record<string, unknown>>();
   const uniqueLiveJoinRows: Record<string, unknown>[] = [];
@@ -500,18 +653,30 @@ function summarizeFieldRegionRows(
       const wordPlacement = normalizeWordPlacement(
         record(readbackRow.wordResultPlacement),
       );
+      const pageSpanStatus = classifyPageSpan(normalizedWordPageIndexSpan, runtimePageSpan);
+      const l04FrameProjection = projectFieldToL04Frame({
+        docId,
+        normalizedWordPageIndexSpan,
+        runtimePageSpan,
+        pageSpanStatus,
+        wordPlacement,
+        pageFramesByDocId,
+      });
       const pageLocalGeometry: AdjacentGeometryPageLocalFieldGeometry = {
         expectedPageSpan,
         normalizedWordPageIndexSpan,
         runtimePageSpan,
-        pageSpanStatus: classifyPageSpan(normalizedWordPageIndexSpan, runtimePageSpan),
+        pageSpanStatus,
         startAnchorTwips: wordPlacement?.startXYTwips,
         endAnchorTwips: wordPlacement?.endXYTwips,
+        l04FrameProjection,
         coordinateSpace: "word-page-twips",
         precision: "word-page-local-calibration",
         normalizationStatus:
-          wordPlacement?.startXYTwips || wordPlacement?.endXYTwips
-            ? "word-page-local-awaiting-l04-frame-projection"
+          l04FrameProjection.status === "projected-l04-frame"
+            ? "l04-frame-twips-projected"
+            : wordPlacement?.startXYTwips || wordPlacement?.endXYTwips
+              ? "word-page-local-awaiting-l04-frame-projection"
             : "missing-word-placement",
       };
       return {
@@ -562,6 +727,9 @@ function summarizeDocument(
     numberingRowsWithRuntimeFragment: numberingRows.filter(
       (row) => row.runtimeFragmentId !== undefined,
     ).length,
+    numberingRowsJoinedFromL04Readback: numberingRows.filter(
+      (row) => row.runtimeJoinSource === "l04-numbering-readback",
+    ).length,
     numberingParagraphLineRects: sum(
       numberingRows,
       (row) => row.paragraphLineRectCount,
@@ -584,6 +752,19 @@ function summarizeDocument(
     numberingRowsWithPageLocalTextColumn: numberingRows.filter(
       (row) => row.pageLocalGeometry.textColumn !== undefined,
     ).length,
+    numberingRowsWithRuntimePageMatch: numberingRows.filter(
+      (row) => row.pageLocalGeometry.pageIndexStatus === "matches-runtime",
+    ).length,
+    numberingUiaRowsWithRuntimePageMatch: numberingRows.filter(
+      (row) =>
+        hasNumberingUiaCapture(row) &&
+        row.pageLocalGeometry.pageIndexStatus === "matches-runtime",
+    ).length,
+    numberingRowsWithL04FrameProjection: numberingRows.filter(hasL04FrameProjection)
+      .length,
+    numberingUiaRowsWithL04FrameProjection: numberingRows.filter(
+      (row) => hasNumberingUiaCapture(row) && hasL04FrameProjection(row),
+    ).length,
     fieldRegionRows: fieldRegionRows.length,
     fieldRegionRowsWithRuntimeId: fieldRegionRows.filter(
       (row) => row.runtimeFieldRegionId !== undefined,
@@ -604,9 +785,21 @@ function summarizeDocument(
     fieldRegionRowsWithRuntimePageContainment: fieldRegionRows.filter(
       (row) => row.pageLocalGeometry.pageSpanStatus === "contained-in-runtime",
     ).length,
+    fieldRegionRowsWithL04FrameProjection: fieldRegionRows.filter(
+      hasL04FrameProjection,
+    ).length,
+    fieldRegionUiaRowsWithL04FrameProjection: fieldRegionRows.filter(
+      (row) => row.resultLineRectCount > 0 && hasL04FrameProjection(row),
+    ).length,
   };
 }
 
+function hasL04FrameProjection(
+  row: AdjacentGeometryNumberingRowSummary | AdjacentGeometryFieldRegionRowSummary,
+): boolean {
+  return row.pageLocalGeometry.l04FrameProjection.status === "projected-l04-frame";
+}
+
 function hasNumberingUiaCapture(row: AdjacentGeometryNumberingRowSummary): boolean {
   return (
     row.paragraphLineRectCount > 0 ||
@@ -615,6 +808,250 @@ function hasNumberingUiaCapture(row: AdjacentGeometryNumberingRowSummary): boole
   );
 }
 
+function collectPageFramesByDocId(
+  artifacts: readonly unknown[],
+): Map<string, Map<number, AdjacentGeometryPageFrame>> {
+  const byDocId = new Map<string, Map<number, AdjacentGeometryPageFrame>>();
+  for (const artifact of artifacts) {
+    const artifactRecord = record(artifact);
+    const docId = stringValue(artifactRecord.docId);
+    if (!docId) continue;
+    for (const raw of array(artifactRecord.pages)) {
+      const page = record(raw);
+      const pageIndex = numberValue(page.pageIndex);
+      if (pageIndex === undefined) continue;
+      const frame = record(page.frame);
+      const physicalBoundsTwips = normalizeTwipsRect(frame.physicalBoundsTwips);
+      const pageFrame: AdjacentGeometryPageFrame = {
+        pageId: stringValue(page.pageId),
+        pageIndex,
+        frameId: stringValue(frame.frameId),
+        completeness: stringValue(frame.completeness),
+        physicalBoundsTwips,
+      };
+      let docFrames = byDocId.get(docId);
+      if (!docFrames) {
+        docFrames = new Map<number, AdjacentGeometryPageFrame>();
+        byDocId.set(docId, docFrames);
+      }
+      if (!docFrames.has(pageIndex)) docFrames.set(pageIndex, pageFrame);
+    }
+  }
+  return byDocId;
+}
+
+function collectNumberingRuntimeReadbacks(
+  artifacts: readonly unknown[],
+): Map<string, Record<string, unknown>> {
+  const byKey = new Map<string, Record<string, unknown>>();
+  for (const artifact of artifacts) {
+    const artifactRecord = record(artifact);
+    const docId = stringValue(artifactRecord.docId);
+    for (const raw of array(artifactRecord.numberingFragments)) {
+      const row = record(raw);
+      const key = numberingRuntimeReadbackKey(
+        docId ?? stringValue(row.docId),
+        stringValue(row.numberingKey) ?? stringValue(row.runtimeNumberingId),
+        stringValue(row.numberingInstanceId),
+        numberValue(row.level),
+      );
+      if (key && !byKey.has(key)) byKey.set(key, row);
+    }
+  }
+  return byKey;
+}
+
+function numberingRuntimeReadbackForRow(
+  row: Record<string, unknown>,
+  runtimeReadbacksByKey: ReadonlyMap<string, Record<string, unknown>>,
+): Record<string, unknown> | undefined {
+  const key = numberingRuntimeReadbackKey(
+    stringValue(row.docId),
+    stringValue(record(row.canonicalJoinAttempt).numberingKey),
+    stringValue(row.canonicalNumberingInstanceId),
+    numberValue(row.canonicalLevel),
+  );
+  return key ? runtimeReadbacksByKey.get(key) : undefined;
+}
+
+function projectNumberingToL04Frame(input: {
+  readonly docId: string;
+  readonly normalizedWordPageIndex: number | undefined;
+  readonly runtimePageIndex: number | undefined;
+  readonly pageIndexStatus: AdjacentGeometryPageIndexStatus;
+  readonly markerLane: AdjacentGeometryTwipsRect | undefined;
+  readonly textColumn: AdjacentGeometryTwipsRect | undefined;
+  readonly pageFramesByDocId: ReadonlyMap<string, ReadonlyMap<number, AdjacentGeometryPageFrame>>;
+}): AdjacentGeometryL04FrameProjection {
+  if (input.pageIndexStatus === "word-page-missing") {
+    return baseFrameProjection("word-page-missing");
+  }
+  if (input.pageIndexStatus === "runtime-missing") {
+    return baseFrameProjection("runtime-page-missing", input.normalizedWordPageIndex);
+  }
+  if (input.pageIndexStatus === "differs-from-runtime") {
+    return baseFrameProjection(
+      "page-index-differs-from-runtime",
+      input.normalizedWordPageIndex,
+    );
+  }
+  if (!input.markerLane && !input.textColumn) {
+    return baseFrameProjection(
+      "missing-word-page-local-geometry",
+      input.normalizedWordPageIndex,
+    );
+  }
+  const frame = pageFrameFor(input.pageFramesByDocId, input.docId, input.runtimePageIndex);
+  if (!frame?.physicalBoundsTwips) {
+    return baseFrameProjection("missing-l04-page-frame", input.runtimePageIndex);
+  }
+  return {
+    pageIndex: input.runtimePageIndex,
+    pageId: frame.pageId,
+    frameId: frame.frameId,
+    frameCompleteness: frame.completeness,
+    physicalBoundsTwips: frame.physicalBoundsTwips,
+    markerLane: addFrameOrigin(input.markerLane, frame.physicalBoundsTwips),
+    textColumn: addFrameOrigin(input.textColumn, frame.physicalBoundsTwips),
+    coordinateSpace: "l04-frame-twips",
+    precision: "word-page-local-calibration",
+    status: "projected-l04-frame",
+  };
+}
+
+function projectFieldToL04Frame(input: {
+  readonly docId: string;
+  readonly normalizedWordPageIndexSpan: AdjacentGeometryPageSpan | undefined;
+  readonly runtimePageSpan: AdjacentGeometryPageSpan | undefined;
+  readonly pageSpanStatus: AdjacentGeometryPageLocalFieldGeometry["pageSpanStatus"];
+  readonly wordPlacement:
+    | AdjacentGeometryFieldRegionRowSummary["wordPlacement"]
+    | undefined;
+  readonly pageFramesByDocId: ReadonlyMap<string, ReadonlyMap<number, AdjacentGeometryPageFrame>>;
+}): AdjacentGeometryL04FrameProjection {
+  const normalizedStart = input.normalizedWordPageIndexSpan?.startPage;
+  if (normalizedStart == null) return baseFrameProjection("word-page-missing");
+  if (!input.runtimePageSpan || input.runtimePageSpan.startPage == null) {
+    return baseFrameProjection("runtime-page-missing", normalizedStart);
+  }
+  if (
+    input.pageSpanStatus !== "matches-runtime" &&
+    input.pageSpanStatus !== "contained-in-runtime"
+  ) {
+    return baseFrameProjection("page-index-differs-from-runtime", normalizedStart);
+  }
+  if (!input.wordPlacement?.startXYTwips && !input.wordPlacement?.endXYTwips) {
+    return baseFrameProjection("missing-word-page-local-geometry", normalizedStart);
+  }
+  const frame = pageFrameFor(
+    input.pageFramesByDocId,
+    input.docId,
+    input.runtimePageSpan.startPage,
+  );
+  if (!frame?.physicalBoundsTwips) {
+    return baseFrameProjection("missing-l04-page-frame", input.runtimePageSpan.startPage);
+  }
+  return {
+    pageIndex: input.runtimePageSpan.startPage,
+    pageId: frame.pageId,
+    frameId: frame.frameId,
+    frameCompleteness: frame.completeness,
+    physicalBoundsTwips: frame.physicalBoundsTwips,
+    fieldStartAnchorTwips: addFrameOriginToPoint(
+      input.wordPlacement.startXYTwips,
+      frame.physicalBoundsTwips,
+    ),
+    fieldEndAnchorTwips: addFrameOriginToPoint(
+      input.wordPlacement.endXYTwips,
+      frame.physicalBoundsTwips,
+    ),
+    coordinateSpace: "l04-frame-twips",
+    precision: "word-page-local-calibration",
+    status: "projected-l04-frame",
+  };
+}
+
+function baseFrameProjection(
+  status: AdjacentGeometryL04FrameProjection["status"],
+  pageIndex?: number,
+): AdjacentGeometryL04FrameProjection {
+  return {
+    pageIndex,
+    coordinateSpace: "l04-frame-twips",
+    precision: "word-page-local-calibration",
+    status,
+  };
+}
+
+function pageFrameFor(
+  pageFramesByDocId: ReadonlyMap<string, ReadonlyMap<number, AdjacentGeometryPageFrame>>,
+  docId: string,
+  pageIndex: number | undefined,
+): AdjacentGeometryPageFrame | undefined {
+  return pageIndex === undefined ? undefined : pageFramesByDocId.get(docId)?.get(pageIndex);
+}
+
+function addFrameOrigin(
+  rect: AdjacentGeometryTwipsRect | undefined,
+  frame: AdjacentGeometryTwipsRect,
+): AdjacentGeometryTwipsRect | undefined {
+  if (!rect) return undefined;
+  return {
+    xTwips:
+      rect.xTwips === undefined || frame.xTwips === undefined
+        ? rect.xTwips
+        : rect.xTwips + frame.xTwips,
+    yTwips:
+      rect.yTwips === undefined || frame.yTwips === undefined
+        ? rect.yTwips
+        : rect.yTwips + frame.yTwips,
+    widthTwips: rect.widthTwips,
+    heightTwips: rect.heightTwips,
+  };
+}
+
+function addFrameOriginToPoint(
+  point: { readonly x?: number; readonly y?: number } | undefined,
+  frame: AdjacentGeometryTwipsRect,
+): { readonly x?: number; readonly y?: number } | undefined {
+  if (!point) return undefined;
+  return {
+    x:
+      point.x === undefined || frame.xTwips === undefined
+        ? point.x
+        : point.x + frame.xTwips,
+    y:
+      point.y === undefined || frame.yTwips === undefined
+        ? point.y
+        : point.y + frame.yTwips,
+  };
+}
+
+function classifyPageIndex(
+  normalizedWordPageIndex: number | undefined,
+  runtimePageIndex: number | undefined,
+): AdjacentGeometryPageIndexStatus {
+  if (normalizedWordPageIndex === undefined) return "word-page-missing";
+  if (runtimePageIndex === undefined) return "runtime-missing";
+  return normalizedWordPageIndex === runtimePageIndex
+    ? "matches-runtime"
+    : "differs-from-runtime";
+}
+
+function numberingRuntimeReadbackKey(
+  docId: string | undefined,
+  numberingKeyValue: string | undefined,
+  numberingInstanceId: string | undefined,
+  level: number | undefined,
+): string | undefined {
+  return docId &&
+    numberingKeyValue &&
+    numberingInstanceId &&
+    level !== undefined
+    ? `${docId}\0${numberingKeyValue}\0${numberingInstanceId}\0${level}`
+    : undefined;
+}
+
 function normalizeRects(raw: unknown): readonly AdjacentGeometryRect[] {
   if (Array.isArray(raw)) return raw.map(normalizeRect).filter(isRect);
   const maybeRect = normalizeRect(raw);