@beyondwork/docx-react-component 1.0.106 → 1.0.108

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

@@ -0,0 +1,835 @@
+export interface AdjacentGeometryRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly unit: "screenPx" | string;
+  readonly approxTwips?: {
+    readonly x?: number;
+    readonly y?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly unit?: "twipsApproxFromScreen" | string;
+  };
+}
+
+export interface AdjacentGeometryTwipsRect {
+  readonly xTwips?: number;
+  readonly yTwips?: number;
+  readonly widthTwips?: number;
+  readonly heightTwips?: number;
+}
+
+export interface AdjacentGeometryPageSpan {
+  readonly startPage?: number | null;
+  readonly endPage?: number | null;
+}
+
+export interface AdjacentGeometryPageLocalNumberingGeometry {
+  readonly wordPage?: number;
+  readonly runtimePageIndex?: number;
+  readonly runtimeFragmentId?: string;
+  readonly markerLane?: AdjacentGeometryTwipsRect;
+  readonly textColumn?: AdjacentGeometryTwipsRect;
+  readonly coordinateSpace: "word-page-twips";
+  readonly precision: "word-page-local-calibration";
+  readonly normalizationStatus:
+    | "word-page-local-awaiting-l04-frame-projection"
+    | "missing-word-page-local-lane";
+}
+
+export interface AdjacentGeometryPageLocalFieldGeometry {
+  readonly expectedPageSpan?: AdjacentGeometryPageSpan;
+  readonly normalizedWordPageIndexSpan?: AdjacentGeometryPageSpan;
+  readonly runtimePageSpan?: AdjacentGeometryPageSpan;
+  readonly pageSpanStatus:
+    | "matches-runtime"
+    | "contained-in-runtime"
+    | "differs-from-runtime"
+    | "runtime-missing"
+    | "expected-missing";
+  readonly startAnchorTwips?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  readonly endAnchorTwips?: {
+    readonly x?: number;
+    readonly y?: number;
+  };
+  readonly coordinateSpace: "word-page-twips";
+  readonly precision: "word-page-local-calibration";
+  readonly normalizationStatus:
+    | "word-page-local-awaiting-l04-frame-projection"
+    | "missing-word-placement";
+}
+
+export interface AdjacentGeometryNumberingRowSummary {
+  readonly docId: string;
+  readonly wordParagraphOrdinalGlobal?: number;
+  readonly canonicalBlockId?: string;
+  readonly runtimeBlockId?: string;
+  readonly runtimeFragmentId?: string;
+  readonly runtimePageIndex?: number;
+  readonly sourceParagraphPath?: string;
+  readonly canonicalNumberingInstanceId?: string;
+  readonly canonicalLevel?: number;
+  readonly markerKind?: string;
+  readonly markerSuffix?: string;
+  readonly wordStartPage?: number;
+  readonly paragraphLineRectCount: number;
+  readonly textOnlyLineRectCount: number;
+  readonly rawMarkerRectCount: number;
+  readonly markerRectCount: number;
+  readonly wrappedLineCount: number;
+  readonly markerLane?: {
+    readonly xTwips?: number;
+    readonly yTwips?: number;
+    readonly widthTwips?: number;
+    readonly heightTwips?: number;
+  };
+  readonly textColumn?: {
+    readonly xTwips?: number;
+    readonly yTwips?: number;
+    readonly widthTwips?: number;
+    readonly heightTwips?: number;
+  };
+  readonly pageLocalGeometry: AdjacentGeometryPageLocalNumberingGeometry;
+  readonly rangeMappingMethod?: string;
+  readonly coordinateSpace: "screen-px";
+  readonly precision: "screen-space-approximate";
+  readonly normalizationStatus: "awaiting-l04-page-frame-normalization";
+}
+
+export interface AdjacentGeometryFieldRegionRowSummary {
+  readonly docId: string;
+  readonly wordFieldOrdinalGlobal?: number;
+  readonly canonicalFieldId?: string;
+  readonly canonicalBlockId?: string;
+  readonly runtimeFieldRegionId?: string;
+  readonly runtimeFragmentId?: string;
+  readonly runtimePageSpan?: {
+    readonly startPage?: number | null;
+    readonly endPage?: number | null;
+  };
+  readonly expectedPageSpan?: {
+    readonly startPage?: number | null;
+    readonly endPage?: number | null;
+  };
+  readonly pageLocalGeometry: AdjacentGeometryPageLocalFieldGeometry;
+  readonly instructionFamily?: string;
+  readonly resultLineRectCount: number;
+  readonly wordPlacement?: {
+    readonly startPage?: number;
+    readonly endPage?: number;
+    readonly startXYTwips?: {
+      readonly x?: number;
+      readonly y?: number;
+    };
+    readonly endXYTwips?: {
+      readonly x?: number;
+      readonly y?: number;
+    };
+  };
+  readonly coordinateSpace: "screen-px";
+  readonly precision: "screen-space-approximate";
+  readonly normalizationStatus:
+    | "runtime-id-paired-awaiting-page-frame-normalization"
+    | "awaiting-runtime-field-region-id";
+}
+
+export interface AdjacentGeometryDocumentSummary {
+  readonly docId: string;
+  readonly numberingRows: number;
+  readonly numberingRowsWithRuntimeFragment: number;
+  readonly numberingParagraphLineRects: number;
+  readonly numberingTextOnlyLineRects: number;
+  readonly numberingRawMarkerRectRows: number;
+  readonly numberingMarkerRects: number;
+  readonly numberingRowsWithMissingMarkerRectGeometry: number;
+  readonly numberingWrappedRows: number;
+  readonly numberingRowsWithUiaCapture: number;
+  readonly numberingRowsWithPageLocalMarkerLane: number;
+  readonly numberingRowsWithPageLocalTextColumn: number;
+  readonly fieldRegionRows: number;
+  readonly fieldRegionRowsWithRuntimeId: number;
+  readonly fieldRegionResultLineRects: number;
+  readonly fieldRegionRowsWithUiaCapture: number;
+  readonly fieldRegionRowsWithWordPlacement: number;
+  readonly fieldRegionRowsWithRuntimePageMatch: number;
+  readonly fieldRegionRowsWithRuntimePageContainment: number;
+}
+
+export interface AdjacentGeometryIntakeSummary {
+  readonly schemaVersion: "layer-05-adjacent-geometry-intake/v0";
+  readonly generatedAtUtc: string;
+  readonly sourceRuns: {
+    readonly adjacentLiveWordJoins: string;
+    readonly adjacentUiaNumberingRects: string;
+    readonly fieldRegionRuntimeReadbackVm: string;
+  };
+  readonly totals: {
+    readonly numberingRows: number;
+    readonly numberingRowsWithRuntimeFragment: number;
+    readonly numberingParagraphLineRects: number;
+    readonly numberingTextOnlyLineRects: number;
+    readonly numberingRawMarkerRectRows: number;
+    readonly numberingMarkerRects: number;
+    readonly numberingRowsWithMissingMarkerRectGeometry: number;
+    readonly numberingWrappedRows: number;
+    readonly numberingRowsWithUiaCapture: number;
+    readonly numberingRowsWithPageLocalMarkerLane: number;
+    readonly numberingRowsWithPageLocalTextColumn: number;
+    readonly fieldRegionRows: number;
+    readonly fieldRegionRowsWithRuntimeId: number;
+    readonly fieldRegionResultLineRects: number;
+    readonly fieldRegionRowsWithUiaCapture: number;
+    readonly fieldRegionRowsWithWordPlacement: number;
+    readonly fieldRegionRowsWithRuntimePageMatch: number;
+    readonly fieldRegionRowsWithRuntimePageContainment: number;
+  };
+  readonly routing: {
+    readonly routedTo: "L05";
+    readonly axes: readonly ["numbering-marker-geometry", "field-result-geometry"];
+    readonly coordinateSpace: "screen-px";
+    readonly precision: "screen-space-approximate";
+    readonly requiredUpstreamFact: "L04 page/frame normalization";
+  };
+  readonly pageLocalNormalization: {
+    readonly coordinateSpace: "word-page-twips";
+    readonly precision: "word-page-local-calibration";
+    readonly requiredUpstreamFact: "L04 frame-to-pixel projection";
+    readonly compositorReady: false;
+  };
+  readonly documents: readonly AdjacentGeometryDocumentSummary[];
+  readonly numberingRows: readonly AdjacentGeometryNumberingRowSummary[];
+  readonly fieldRegionRows: readonly AdjacentGeometryFieldRegionRowSummary[];
+}
+
+export function summarizeAdjacentGeometryIntake(input: {
+  readonly generatedAtUtc: string;
+  readonly sourceRuns: AdjacentGeometryIntakeSummary["sourceRuns"];
+  readonly numberingArtifact: unknown;
+  readonly numberingLiveJoinArtifacts: readonly unknown[];
+  readonly fieldRegionRuntimeReadback: unknown;
+  readonly fieldRegionLiveJoinArtifacts: readonly unknown[];
+}): AdjacentGeometryIntakeSummary {
+  const numberingRows = summarizeNumberingRows(
+    input.numberingArtifact,
+    input.numberingLiveJoinArtifacts,
+  );
+  const fieldRegionRows = summarizeFieldRegionRows(
+    input.fieldRegionRuntimeReadback,
+    input.fieldRegionLiveJoinArtifacts,
+  );
+  const docIds = [
+    ...new Set([
+      ...numberingRows.map((row) => row.docId),
+      ...fieldRegionRows.map((row) => row.docId),
+    ]),
+  ].sort();
+  return {
+    schemaVersion: "layer-05-adjacent-geometry-intake/v0",
+    generatedAtUtc: input.generatedAtUtc,
+    sourceRuns: input.sourceRuns,
+    totals: {
+      numberingRows: numberingRows.length,
+      numberingRowsWithRuntimeFragment: numberingRows.filter(
+        (row) => row.runtimeFragmentId !== undefined,
+      ).length,
+      numberingParagraphLineRects: sum(
+        numberingRows,
+        (row) => row.paragraphLineRectCount,
+      ),
+      numberingTextOnlyLineRects: sum(
+        numberingRows,
+        (row) => row.textOnlyLineRectCount,
+      ),
+      numberingRawMarkerRectRows: sum(numberingRows, (row) => row.rawMarkerRectCount),
+      numberingMarkerRects: sum(numberingRows, (row) => row.markerRectCount),
+      numberingRowsWithMissingMarkerRectGeometry: numberingRows.filter(
+        (row) => row.rawMarkerRectCount > row.markerRectCount,
+      ).length,
+      numberingWrappedRows: numberingRows.filter((row) => row.wrappedLineCount > 1)
+        .length,
+      numberingRowsWithUiaCapture: numberingRows.filter(hasNumberingUiaCapture).length,
+      numberingRowsWithPageLocalMarkerLane: numberingRows.filter(
+        (row) => row.pageLocalGeometry.markerLane !== undefined,
+      ).length,
+      numberingRowsWithPageLocalTextColumn: numberingRows.filter(
+        (row) => row.pageLocalGeometry.textColumn !== undefined,
+      ).length,
+      fieldRegionRows: fieldRegionRows.length,
+      fieldRegionRowsWithRuntimeId: fieldRegionRows.filter(
+        (row) => row.runtimeFieldRegionId !== undefined,
+      ).length,
+      fieldRegionResultLineRects: sum(
+        fieldRegionRows,
+        (row) => row.resultLineRectCount,
+      ),
+      fieldRegionRowsWithUiaCapture: fieldRegionRows.filter(
+        (row) => row.resultLineRectCount > 0,
+      ).length,
+      fieldRegionRowsWithWordPlacement: fieldRegionRows.filter(
+        (row) => row.pageLocalGeometry.startAnchorTwips !== undefined,
+      ).length,
+      fieldRegionRowsWithRuntimePageMatch: fieldRegionRows.filter(
+        (row) => row.pageLocalGeometry.pageSpanStatus === "matches-runtime",
+      ).length,
+      fieldRegionRowsWithRuntimePageContainment: fieldRegionRows.filter(
+        (row) => row.pageLocalGeometry.pageSpanStatus === "contained-in-runtime",
+      ).length,
+    },
+    routing: {
+      routedTo: "L05",
+      axes: ["numbering-marker-geometry", "field-result-geometry"],
+      coordinateSpace: "screen-px",
+      precision: "screen-space-approximate",
+      requiredUpstreamFact: "L04 page/frame normalization",
+    },
+    pageLocalNormalization: {
+      coordinateSpace: "word-page-twips",
+      precision: "word-page-local-calibration",
+      requiredUpstreamFact: "L04 frame-to-pixel projection",
+      compositorReady: false,
+    },
+    documents: docIds.map((docId) =>
+      summarizeDocument(
+        docId,
+        numberingRows.filter((row) => row.docId === docId),
+        fieldRegionRows.filter((row) => row.docId === docId),
+      ),
+    ),
+    numberingRows,
+    fieldRegionRows,
+  };
+}
+
+function summarizeNumberingRows(
+  artifact: unknown,
+  liveJoinArtifacts: readonly unknown[],
+): readonly AdjacentGeometryNumberingRowSummary[] {
+  const uiaRowsByKey = new Map<string, Record<string, unknown>>();
+  for (const raw of array(record(artifact).rows)) {
+    const row = record(raw);
+    const key = numberingKey(
+      stringValue(row.docId) ?? stringValue(record(row.targetJoin).docId),
+      numberValue(row.wordParagraphOrdinalGlobal) ??
+        numberValue(record(row.targetJoin).wordParagraphOrdinalGlobal),
+    );
+    if (key) uiaRowsByKey.set(key, row);
+  }
+
+  const liveRows = liveJoinArtifacts.flatMap((artifact) =>
+    array(record(artifact).numberingRows).map(record),
+  );
+  const rows = liveRows.length > 0
+    ? liveRows.filter((row) => stringValue(row.runtimeFragmentId) !== undefined)
+    : array(record(artifact).rows).map(record);
+
+  return rows
+    .map((raw) => {
+      const row = record(raw);
+      const rowTargetJoin = record(row.targetJoin);
+      const docId =
+        stringValue(row.docId) ?? stringValue(rowTargetJoin.docId) ?? "unknown";
+      const wordParagraphOrdinalGlobal =
+        numberValue(row.wordParagraphOrdinalGlobal) ??
+        numberValue(rowTargetJoin.wordParagraphOrdinalGlobal);
+      const uiaRow =
+        uiaRowsByKey.get(numberingKey(docId, wordParagraphOrdinalGlobal) ?? "") ??
+        {};
+      const uiaTargetJoin = record(uiaRow.targetJoin);
+      const paragraphLineRects = chooseRects(
+        uiaRow.paragraphLineRects,
+        row.paragraphLineRects,
+      );
+      const textOnlyLineRects = chooseRects(
+        uiaRow.textOnlyLineRects,
+        row.textOnlyLineRects,
+      );
+      const rawMarkerRects = chooseRawArray(uiaRow.markerRects, row.markerRects);
+      const markerRects = chooseRects(uiaRow.markerRects, row.markerRects);
+      const markerLane =
+        normalizeTwipsRect(row.markerLane) ?? normalizeTwipsRect(uiaTargetJoin.markerLane);
+      const textColumn =
+        normalizeTwipsRect(row.textColumn) ?? normalizeTwipsRect(uiaTargetJoin.textColumn);
+      const runtimeFragmentId =
+        stringValue(row.runtimeFragmentId) ?? stringValue(uiaTargetJoin.runtimeFragmentId);
+      const runtimePageIndex =
+        numberValue(row.runtimePageIndex) ?? numberValue(uiaTargetJoin.runtimePageIndex);
+      const wordStartPage =
+        numberValue(record(row.pageSpan).startPage) ??
+        numberValue(row.wordStartPage) ??
+        numberValue(uiaRow.wordStartPage);
+      const pageLocalGeometry: AdjacentGeometryPageLocalNumberingGeometry = {
+        wordPage: wordStartPage,
+        runtimePageIndex,
+        runtimeFragmentId,
+        markerLane,
+        textColumn,
+        coordinateSpace: "word-page-twips",
+        precision: "word-page-local-calibration",
+        normalizationStatus:
+          markerLane || textColumn
+            ? "word-page-local-awaiting-l04-frame-projection"
+            : "missing-word-page-local-lane",
+      };
+      return {
+        docId,
+        wordParagraphOrdinalGlobal,
+        canonicalBlockId:
+          stringValue(row.canonicalBlockId) ?? stringValue(uiaTargetJoin.canonicalBlockId),
+        runtimeBlockId:
+          stringValue(row.runtimeBlockId) ?? stringValue(uiaTargetJoin.runtimeBlockId),
+        runtimeFragmentId,
+        runtimePageIndex,
+        sourceParagraphPath:
+          stringValue(row.sourceParagraphPath) ??
+          stringValue(uiaTargetJoin.sourceParagraphPath),
+        canonicalNumberingInstanceId:
+          stringValue(row.canonicalNumberingInstanceId) ??
+          stringValue(uiaTargetJoin.canonicalNumberingInstanceId),
+        canonicalLevel:
+          numberValue(row.canonicalLevel) ?? numberValue(uiaTargetJoin.canonicalLevel),
+        markerKind: stringValue(row.markerKind) ?? stringValue(uiaTargetJoin.markerKind),
+        markerSuffix:
+          stringValue(row.markerSuffix) ?? stringValue(uiaTargetJoin.markerSuffix),
+        wordStartPage,
+        paragraphLineRectCount: paragraphLineRects.length,
+        textOnlyLineRectCount: textOnlyLineRects.length,
+        rawMarkerRectCount: rawMarkerRects.length,
+        markerRectCount: markerRects.length,
+        wrappedLineCount: Math.max(paragraphLineRects.length, textOnlyLineRects.length),
+        markerLane,
+        textColumn,
+        pageLocalGeometry,
+        rangeMappingMethod:
+          stringValue(uiaRow.rangeMappingMethod) ?? stringValue(row.rangeMappingMethod),
+        coordinateSpace: "screen-px" as const,
+        precision: "screen-space-approximate" as const,
+        normalizationStatus: "awaiting-l04-page-frame-normalization" as const,
+      };
+    })
+    .sort(
+      (a, b) =>
+        a.docId.localeCompare(b.docId) ||
+        compareOptionalNumber(
+          a.wordParagraphOrdinalGlobal,
+          b.wordParagraphOrdinalGlobal,
+        ),
+    );
+}
+
+function summarizeFieldRegionRows(
+  runtimeReadback: unknown,
+  liveJoinArtifacts: readonly unknown[],
+): readonly AdjacentGeometryFieldRegionRowSummary[] {
+  const liveJoinByOrdinalKey = new Map<string, Record<string, unknown>>();
+  const uniqueLiveJoinRows: Record<string, unknown>[] = [];
+  const seenRuntimeKeys = new Set<string>();
+  for (const artifact of liveJoinArtifacts) {
+    for (const raw of array(record(artifact).fields)) {
+      const row = record(raw);
+      const key = fieldKey(
+        stringValue(row.docId),
+        numberValue(row.wordFieldOrdinalGlobal),
+      );
+      if (key) liveJoinByOrdinalKey.set(key, row);
+      const runtimeKey = fieldRuntimeKey(
+        stringValue(row.docId),
+        stringValue(row.runtimeFieldRegionId),
+      );
+      if (!runtimeKey || seenRuntimeKeys.has(runtimeKey)) continue;
+      seenRuntimeKeys.add(runtimeKey);
+      uniqueLiveJoinRows.push(row);
+    }
+  }
+
+  const readbackByKey = new Map<string, Record<string, unknown>>();
+  for (const raw of array(record(runtimeReadback).rows)) {
+    const row = record(raw);
+    const key = fieldKey(
+      stringValue(row.docId) ?? stringValue(record(row.targetJoin).docId),
+      numberValue(row.wordFieldOrdinalGlobal) ??
+        numberValue(record(row.targetJoin).wordFieldOrdinalGlobal),
+    );
+    if (key) readbackByKey.set(key, row);
+  }
+
+  const rows = uniqueLiveJoinRows.length > 0
+    ? uniqueLiveJoinRows
+    : array(record(runtimeReadback).rows).map(record);
+
+  return rows
+    .map((raw) => {
+      const liveJoinCandidate = record(raw);
+      const docId = stringValue(liveJoinCandidate.docId) ?? "unknown";
+      const wordFieldOrdinalGlobal = numberValue(
+        liveJoinCandidate.wordFieldOrdinalGlobal,
+      );
+      const readbackRow =
+        readbackByKey.get(fieldKey(docId, wordFieldOrdinalGlobal) ?? "") ?? {};
+      const targetJoin = record(readbackRow.targetJoin);
+      const liveJoin =
+        liveJoinByOrdinalKey.get(fieldKey(docId, wordFieldOrdinalGlobal) ?? "") ??
+        liveJoinCandidate;
+      const liveRuntimePageSpan = record(liveJoin.runtimePageSpan);
+      const runtimePageSpan = normalizePageSpan(
+        liveRuntimePageSpan,
+        record(record(readbackRow.runtime).runtimePageSpan),
+        record(targetJoin.runtimePageSpan),
+      );
+      const expectedGraphOutput = record(readbackRow.expectedGraphOutput);
+      const expectedPageSpan = normalizePageSpan(
+        record(liveJoin.resultPageSpan),
+        record(readbackRow.wordResultPlacement),
+        record(expectedGraphOutput.expectedPageSpan),
+        record(targetJoin.resultPageSpan),
+      );
+      const normalizedWordPageIndexSpan = normalizeWordPageSpanToPageIndexSpan(
+        expectedPageSpan,
+      );
+      const uia = record(readbackRow.uia);
+      const resultLineRects = normalizeRects(uia.resultLineRectsScreen);
+      const hasRuntimeFieldRegionId =
+        stringValue(liveJoin.runtimeFieldRegionId) !== undefined;
+      const normalizationStatus: AdjacentGeometryFieldRegionRowSummary["normalizationStatus"] =
+        hasRuntimeFieldRegionId
+          ? "runtime-id-paired-awaiting-page-frame-normalization"
+          : "awaiting-runtime-field-region-id";
+      const wordPlacement = normalizeWordPlacement(
+        record(readbackRow.wordResultPlacement),
+      );
+      const pageLocalGeometry: AdjacentGeometryPageLocalFieldGeometry = {
+        expectedPageSpan,
+        normalizedWordPageIndexSpan,
+        runtimePageSpan,
+        pageSpanStatus: classifyPageSpan(normalizedWordPageIndexSpan, runtimePageSpan),
+        startAnchorTwips: wordPlacement?.startXYTwips,
+        endAnchorTwips: wordPlacement?.endXYTwips,
+        coordinateSpace: "word-page-twips",
+        precision: "word-page-local-calibration",
+        normalizationStatus:
+          wordPlacement?.startXYTwips || wordPlacement?.endXYTwips
+            ? "word-page-local-awaiting-l04-frame-projection"
+            : "missing-word-placement",
+      };
+      return {
+        docId,
+        wordFieldOrdinalGlobal,
+        canonicalFieldId:
+          stringValue(liveJoin.canonicalFieldId) ??
+          stringValue(targetJoin.canonicalFieldId),
+        canonicalBlockId:
+          stringValue(liveJoin.canonicalBlockId) ??
+          stringValue(targetJoin.canonicalBlockId),
+        runtimeFieldRegionId:
+          stringValue(liveJoin.runtimeFieldRegionId) ??
+          stringValue(targetJoin.runtimeFieldRegionId) ??
+          stringValue(record(readbackRow.runtime).runtimeFieldRegionId),
+        runtimeFragmentId:
+          stringValue(liveJoin.runtimeFragmentId) ??
+          stringValue(targetJoin.runtimeFragmentId) ??
+          stringValue(record(readbackRow.runtime).runtimeFragmentId),
+        runtimePageSpan,
+        expectedPageSpan,
+        pageLocalGeometry,
+        instructionFamily:
+          stringValue(liveJoin.instructionFamily) ??
+          stringValue(targetJoin.instructionFamily),
+        resultLineRectCount: resultLineRects.length,
+        wordPlacement,
+        coordinateSpace: "screen-px" as const,
+        precision: "screen-space-approximate" as const,
+        normalizationStatus,
+      };
+    })
+    .sort(
+      (a, b) =>
+        a.docId.localeCompare(b.docId) ||
+        compareOptionalNumber(a.wordFieldOrdinalGlobal, b.wordFieldOrdinalGlobal),
+    );
+}
+
+function summarizeDocument(
+  docId: string,
+  numberingRows: readonly AdjacentGeometryNumberingRowSummary[],
+  fieldRegionRows: readonly AdjacentGeometryFieldRegionRowSummary[],
+): AdjacentGeometryDocumentSummary {
+  return {
+    docId,
+    numberingRows: numberingRows.length,
+    numberingRowsWithRuntimeFragment: numberingRows.filter(
+      (row) => row.runtimeFragmentId !== undefined,
+    ).length,
+    numberingParagraphLineRects: sum(
+      numberingRows,
+      (row) => row.paragraphLineRectCount,
+    ),
+    numberingTextOnlyLineRects: sum(
+      numberingRows,
+      (row) => row.textOnlyLineRectCount,
+    ),
+    numberingRawMarkerRectRows: sum(numberingRows, (row) => row.rawMarkerRectCount),
+    numberingMarkerRects: sum(numberingRows, (row) => row.markerRectCount),
+    numberingRowsWithMissingMarkerRectGeometry: numberingRows.filter(
+      (row) => row.rawMarkerRectCount > row.markerRectCount,
+    ).length,
+    numberingWrappedRows: numberingRows.filter((row) => row.wrappedLineCount > 1)
+      .length,
+    numberingRowsWithUiaCapture: numberingRows.filter(hasNumberingUiaCapture).length,
+    numberingRowsWithPageLocalMarkerLane: numberingRows.filter(
+      (row) => row.pageLocalGeometry.markerLane !== undefined,
+    ).length,
+    numberingRowsWithPageLocalTextColumn: numberingRows.filter(
+      (row) => row.pageLocalGeometry.textColumn !== undefined,
+    ).length,
+    fieldRegionRows: fieldRegionRows.length,
+    fieldRegionRowsWithRuntimeId: fieldRegionRows.filter(
+      (row) => row.runtimeFieldRegionId !== undefined,
+    ).length,
+    fieldRegionResultLineRects: sum(
+      fieldRegionRows,
+      (row) => row.resultLineRectCount,
+    ),
+    fieldRegionRowsWithUiaCapture: fieldRegionRows.filter(
+      (row) => row.resultLineRectCount > 0,
+    ).length,
+    fieldRegionRowsWithWordPlacement: fieldRegionRows.filter(
+      (row) => row.pageLocalGeometry.startAnchorTwips !== undefined,
+    ).length,
+    fieldRegionRowsWithRuntimePageMatch: fieldRegionRows.filter(
+      (row) => row.pageLocalGeometry.pageSpanStatus === "matches-runtime",
+    ).length,
+    fieldRegionRowsWithRuntimePageContainment: fieldRegionRows.filter(
+      (row) => row.pageLocalGeometry.pageSpanStatus === "contained-in-runtime",
+    ).length,
+  };
+}
+
+function hasNumberingUiaCapture(row: AdjacentGeometryNumberingRowSummary): boolean {
+  return (
+    row.paragraphLineRectCount > 0 ||
+    row.textOnlyLineRectCount > 0 ||
+    row.rawMarkerRectCount > 0
+  );
+}
+
+function normalizeRects(raw: unknown): readonly AdjacentGeometryRect[] {
+  if (Array.isArray(raw)) return raw.map(normalizeRect).filter(isRect);
+  const maybeRect = normalizeRect(raw);
+  return isRect(maybeRect) ? [maybeRect] : [];
+}
+
+function chooseRects(primary: unknown, fallback: unknown): readonly AdjacentGeometryRect[] {
+  const primaryRects = normalizeRects(primary);
+  return primaryRects.length > 0 ? primaryRects : normalizeRects(fallback);
+}
+
+function chooseRawArray(primary: unknown, fallback: unknown): readonly unknown[] {
+  const primaryArray = array(primary);
+  return primaryArray.length > 0 ? primaryArray : array(fallback);
+}
+
+function normalizeRect(raw: unknown): AdjacentGeometryRect | undefined {
+  const rect = record(raw);
+  const x = numberValue(rect.x);
+  const y = numberValue(rect.y);
+  const width = numberValue(rect.width);
+  const height = numberValue(rect.height);
+  if (x === undefined || y === undefined || width === undefined || height === undefined) {
+    return undefined;
+  }
+  const approxTwips = record(rect.approxTwips);
+  const normalizedApproxTwips = {
+    x: numberValue(approxTwips.x),
+    y: numberValue(approxTwips.y),
+    width: numberValue(approxTwips.width),
+    height: numberValue(approxTwips.height),
+    unit: stringValue(approxTwips.unit),
+  };
+  const hasApproxTwips = Object.values(normalizedApproxTwips).some(
+    (value) => value !== undefined,
+  );
+  return {
+    x,
+    y,
+    width,
+    height,
+    unit: stringValue(rect.unit) ?? "screenPx",
+    approxTwips: hasApproxTwips ? normalizedApproxTwips : undefined,
+  };
+}
+
+function normalizeTwipsRect(raw: unknown):
+  | {
+      readonly xTwips?: number;
+      readonly yTwips?: number;
+      readonly widthTwips?: number;
+      readonly heightTwips?: number;
+    }
+  | undefined {
+  const rect = record(raw);
+  const normalized = {
+    xTwips: numberValue(rect.xTwips),
+    yTwips: numberValue(rect.yTwips),
+    widthTwips: numberValue(rect.widthTwips),
+    heightTwips: numberValue(rect.heightTwips),
+  };
+  return Object.values(normalized).some((value) => value !== undefined)
+    ? normalized
+    : undefined;
+}
+
+function normalizePageSpan(
+  ...candidates: readonly Record<string, unknown>[]
+):
+  | {
+      readonly startPage?: number | null;
+      readonly endPage?: number | null;
+    }
+  | undefined {
+  for (const candidate of candidates) {
+    const startPage = nullableNumberValue(candidate.startPage);
+    const endPage = nullableNumberValue(candidate.endPage);
+    if (startPage !== undefined || endPage !== undefined) {
+      return { startPage, endPage };
+    }
+  }
+  return undefined;
+}
+
+function normalizeWordPageSpanToPageIndexSpan(
+  span: AdjacentGeometryPageSpan | undefined,
+): AdjacentGeometryPageSpan | undefined {
+  if (!span || (span.startPage == null && span.endPage == null)) return undefined;
+  return {
+    startPage: span.startPage == null ? span.startPage : span.startPage - 1,
+    endPage: span.endPage == null ? span.endPage : span.endPage - 1,
+  };
+}
+
+function classifyPageSpan(
+  normalizedExpected: AdjacentGeometryPageSpan | undefined,
+  runtime: AdjacentGeometryPageSpan | undefined,
+): AdjacentGeometryPageLocalFieldGeometry["pageSpanStatus"] {
+  if (
+    !normalizedExpected ||
+    (normalizedExpected.startPage == null && normalizedExpected.endPage == null)
+  ) {
+    return "expected-missing";
+  }
+  if (!runtime || (runtime.startPage == null && runtime.endPage == null)) {
+    return "runtime-missing";
+  }
+  if (
+    normalizedExpected.startPage === runtime.startPage &&
+    normalizedExpected.endPage === runtime.endPage
+  ) {
+    return "matches-runtime";
+  }
+  if (
+    normalizedExpected.startPage != null &&
+    normalizedExpected.endPage != null &&
+    runtime.startPage != null &&
+    runtime.endPage != null &&
+    normalizedExpected.startPage >= runtime.startPage &&
+    normalizedExpected.endPage <= runtime.endPage
+  ) {
+    return "contained-in-runtime";
+  }
+  return "differs-from-runtime";
+}
+
+function normalizeWordPlacement(raw: Record<string, unknown>):
+  | AdjacentGeometryFieldRegionRowSummary["wordPlacement"]
+  | undefined {
+  const startXYTwips = record(raw.startXYTwips);
+  const endXYTwips = record(raw.endXYTwips);
+  const normalized = {
+    startPage: numberValue(raw.startPage),
+    endPage: numberValue(raw.endPage),
+    startXYTwips: {
+      x: numberValue(startXYTwips.x),
+      y: numberValue(startXYTwips.y),
+    },
+    endXYTwips: {
+      x: numberValue(endXYTwips.x),
+      y: numberValue(endXYTwips.y),
+    },
+  };
+  const hasStart = Object.values(normalized.startXYTwips).some(
+    (value) => value !== undefined,
+  );
+  const hasEnd = Object.values(normalized.endXYTwips).some(
+    (value) => value !== undefined,
+  );
+  if (
+    normalized.startPage === undefined &&
+    normalized.endPage === undefined &&
+    !hasStart &&
+    !hasEnd
+  ) {
+    return undefined;
+  }
+  return {
+    startPage: normalized.startPage,
+    endPage: normalized.endPage,
+    startXYTwips: hasStart ? normalized.startXYTwips : undefined,
+    endXYTwips: hasEnd ? normalized.endXYTwips : undefined,
+  };
+}
+
+function fieldKey(docId: string | undefined, ordinal: number | undefined): string | undefined {
+  return docId && ordinal !== undefined ? `${docId}\0${ordinal}` : undefined;
+}
+
+function fieldRuntimeKey(
+  docId: string | undefined,
+  runtimeFieldRegionId: string | undefined,
+): string | undefined {
+  return docId && runtimeFieldRegionId ? `${docId}\0${runtimeFieldRegionId}` : undefined;
+}
+
+function numberingKey(docId: string | undefined, ordinal: number | undefined):
+  | string
+  | undefined {
+  return docId && ordinal !== undefined ? `${docId}\0${ordinal}` : undefined;
+}
+
+function isRect(value: AdjacentGeometryRect | undefined): value is AdjacentGeometryRect {
+  return value !== undefined;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function array(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+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 nullableNumberValue(value: unknown): number | null | undefined {
+  return value === null ? null : numberValue(value);
+}
+
+function compareOptionalNumber(a: number | undefined, b: number | undefined): number {
+  if (a === undefined && b === undefined) return 0;
+  if (a === undefined) return 1;
+  if (b === undefined) return -1;
+  return a - b;
+}
+
+function sum<T>(items: readonly T[], read: (item: T) => number): number {
+  return items.reduce((total, item) => total + read(item), 0);
+}