@beyondwork/docx-react-component 1.0.106 → 1.0.108

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

@@ -26,6 +26,7 @@
 import type { EditorStoryTarget } from "../../api/public-types";
 import type {
   PublicMeasurementFidelity,
+  PublicPageFrame,
   PublicPageRegion,
 } from "../layout/public-facet.ts";
 
@@ -119,17 +120,28 @@ export interface GeometryPrecisionCounts {
 export interface GeometryIndexCoverage {
   status: GeometryRehydrationStatus;
   pageCount: number;
+  pageFrameCompleteness: GeometryPageFrameCompletenessCounts;
   regionCount: number;
   sliceCount: number;
   lineCount: number;
   anchorCount: number;
   hitTargetCount: number;
   semanticEntryCount: number;
+  pageLocalFieldLedgerCount: number;
   replacementEnvelopeCount: number;
   objectHandleCount: number;
+  layoutDivergenceObjectCount: number;
+  splitRowCarryCount: number;
   precision: GeometryPrecisionCounts;
 }
 
+export type GeometryPageFrameCompleteness = PublicPageFrame["completeness"];
+
+export type GeometryPageFrameCompletenessCounts = Record<
+  GeometryPageFrameCompleteness,
+  number
+>;
+
 export type GeometrySourceIdentityJoinKind = "direct" | "block-scoped";
 
 /**
@@ -183,6 +195,10 @@ export interface GeometryIndexPage {
   pageIndex: number;
   rect: GeometryRect;
   regionIds: readonly string[];
+  frameCompleteness: GeometryPageFrameCompleteness;
+  displayPageNumber?: number;
+  layoutDivergenceIds?: readonly string[];
+  layoutDivergenceObjectIds?: readonly string[];
 }
 
 export interface GeometryIndexRegion {
@@ -255,6 +271,8 @@ export interface GeometryHitTarget {
 
 export type SemanticDisplayEntryKind =
   | "text-line"
+  | "field-region"
+  | "page-local-field-ledger"
   | "numbering-marker"
   | "table-frame"
   | "table-row"
@@ -269,6 +287,34 @@ export type SemanticDisplayEntryKind =
   | "border"
   | "debug-classification";
 
+export interface GeometryTableRowRange {
+  from: number;
+  to: number;
+  totalRows: number;
+}
+
+export interface GeometryTableSplitRowCarry {
+  rowIndex: number;
+  continuesFromPreviousPage: boolean;
+  continuesToNextPage: boolean;
+}
+
+export interface GeometryTableVerticalMergeCarry {
+  columnIndex: number;
+  restartRowIndex: number;
+}
+
+export interface GeometryTableContinuation {
+  sequenceIndex?: number;
+  sliceCount?: number;
+  rowRange?: GeometryTableRowRange;
+  continuesFromPreviousPage?: boolean;
+  continuesToNextPage?: boolean;
+  repeatedHeaderRowIndexes?: readonly number[];
+  splitRowCarry?: readonly GeometryTableSplitRowCarry[];
+  verticalMergeCarry?: readonly GeometryTableVerticalMergeCarry[];
+}
+
 export interface SemanticDisplayEntry {
   entryId: string;
   kind: SemanticDisplayEntryKind;
@@ -282,6 +328,18 @@ export interface SemanticDisplayEntry {
   fragmentId?: string;
   rowIndex?: number;
   columnIndex?: number;
+  tableContinuation?: GeometryTableContinuation;
+  layoutObjectId?: string;
+  fieldFamilies?: readonly string[];
+  pageLocalStoryId?: string;
+  pageLocalStoryKind?: "header" | "footer";
+  pageLocalStoryVariant?: string;
+  resolvedFieldId?: string;
+  resolvedFieldFamily?: string;
+  resolvedFieldDisplayText?: string;
+  frameCompleteness?: GeometryPageFrameCompleteness;
+  layoutDivergenceIds?: readonly string[];
+  layoutDivergenceObjectIds?: readonly string[];
   rect: GeometryRect;
   status: GeometryRehydrationStatus;
   precision: GeometryPrecision;
@@ -303,6 +361,7 @@ export interface GeometryObjectHandleEntry {
   rects: readonly GeometryRect[];
   status: GeometryRehydrationStatus;
   precision: GeometryPrecision;
+  layoutDivergenceIds?: readonly string[];
   sourceIdentity?: GeometrySourceIdentity;
 }
 

package/src/runtime/geometry/hit-test.ts

@@ -32,7 +32,17 @@ export function resolveHitTest(
   if (!frame) return null;
   for (const page of frame.pages) {
     if (!containsPoint(page.frame, point)) continue;
-    // Check body first — it owns the bulk of the page. Header /
+    // Column regions are explicit L04 projection facts nested inside
+    // the body band. Check them before the broad body region so the
+    // body's between-block snap cannot steal clicks from a populated
+    // column.
+    if (page.regions.columns) {
+      for (const columnRegion of page.regions.columns) {
+        const hit = hitTestStoryRegion(page, point, columnRegion);
+        if (hit) return hit;
+      }
+    }
+    // Check body next — it owns the bulk of the page. Header /
     // footer / footnotes are secondary stories and only matter when
     // the point falls outside the body.
     const bodyHit = hitTestStoryRegion(page, point, page.regions.body);

package/src/runtime/geometry/overlay-rects.ts

@@ -48,8 +48,10 @@ function normalizeVisibleRange(
 
 /**
  * Build the `PageOverlayRect` list from a `GeometryFacet`. Returns
- * `null` when the facet does not resolve page 0 (cold-open) so the
- * caller can fall back to a DOM-measurement path.
+ * `null` when the facet cannot resolve every requested visible page
+ * (cold-open or partial frame) so the caller can fall back to an
+ * explicitly degraded DOM-measurement path instead of painting a
+ * partial page stack.
  */
 export function resolvePageOverlayRectsFromGeometry(
   geometryFacet: GeometryFacet,
@@ -69,7 +71,7 @@ export function resolvePageOverlayRectsFromGeometry(
       if (i < normalizedVisible.start || i >= normalizedVisible.end) continue;
     }
     const page = geometryFacet.getPage(i);
-    if (!page) continue;
+    if (!page) return null;
     rects.push({
       pageId: page.pageId,
       pageIndex: page.pageIndex,

package/src/runtime/geometry/project-anchors.ts

@@ -21,7 +21,7 @@ import type {
   RenderFrame,
   RenderFrameRect,
 } from "../render/index.ts";
-import { emitLayoutGuardWarning } from "../layout/public-facet.ts";
+import { emitLayoutGuardWarning } from "../diagnostics/layout-guard-warning.ts";
 
 export function resolveAnchorRects(
   frame: RenderFrame | null,

package/src/runtime/geometry/word-layout-v2-line-intake.ts

@@ -0,0 +1,323 @@
+export type WordLayoutV2LineIntakeLane = "ccep" | "ccep-redline";
+
+export interface WordLayoutV2LineIntakeDocumentInput {
+  readonly lane: WordLayoutV2LineIntakeLane;
+  readonly runId: string;
+  readonly docId: string;
+  readonly recordPath?: string;
+  readonly artifact: unknown;
+}
+
+export interface WordLayoutV2LineGeometryRect {
+  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 WordLayoutV2LineGeometryRow {
+  readonly lineId?: string;
+  readonly textHash?: string;
+  readonly charLength?: number;
+  readonly rectCount: number;
+  readonly rects: readonly WordLayoutV2LineGeometryRect[];
+}
+
+export interface WordLayoutV2LineGeometryDocumentSummary {
+  readonly lane: WordLayoutV2LineIntakeLane;
+  readonly runId: string;
+  readonly docId: string;
+  readonly recordPath?: string;
+  readonly source?: {
+    readonly fileName?: string;
+    readonly sha256?: string;
+    readonly bytes?: number;
+  };
+  readonly tuple: {
+    readonly zoom?: number;
+    readonly viewportWidth?: number;
+    readonly markupMode?: string;
+    readonly dpi?: number;
+  };
+  readonly word?: {
+    readonly version?: string;
+    readonly build?: string;
+    readonly activePrinter?: string;
+  };
+  readonly comSummary: {
+    readonly pageCount?: number | null;
+    readonly paragraphCount?: number;
+    readonly revisionCount?: number;
+    readonly commentCount?: number;
+  };
+  readonly lineBoxSummary: {
+    readonly status?: string;
+    readonly lineCount: number;
+    readonly lineRows: number;
+    readonly linesWithTextHash: number;
+    readonly linesWithRects: number;
+    readonly rectCount: number;
+    readonly approxTwipsRectCount: number;
+    readonly documentRangeRectCount?: number;
+    readonly firstLineId?: string;
+    readonly lastLineId?: string;
+    readonly coordinateSpace: "screen-px";
+    readonly precision: "screen-space-approximate";
+    readonly normalizationStatus: "awaiting-l04-page-frame-join";
+  };
+  readonly lineRows: readonly WordLayoutV2LineGeometryRow[];
+}
+
+export interface WordLayoutV2LineGeometryIntakeSummary {
+  readonly schemaVersion: "layer-05-word-layout-v2-line-geometry-intake/v0";
+  readonly generatedAtUtc: string;
+  readonly sourceRuns: readonly {
+    readonly runId: string;
+    readonly lane: WordLayoutV2LineIntakeLane;
+    readonly documents: number;
+    readonly lineRows: number;
+    readonly linesWithRects: number;
+    readonly rectCount: number;
+    readonly markupModes: readonly string[];
+  }[];
+  readonly totals: {
+    readonly documents: number;
+    readonly lineRows: number;
+    readonly linesWithRects: number;
+    readonly rectCount: number;
+    readonly approxTwipsRectCount: number;
+    readonly cleanDocuments: number;
+    readonly redlineDocuments: number;
+    readonly cleanLineRows: number;
+    readonly redlineLineRows: number;
+  };
+  readonly routing: {
+    readonly routedTo: "L05";
+    readonly axis: "line-geometry";
+    readonly sourceId: "word-layout-v2.uia.lineBoxes.lines";
+    readonly coordinateSpace: "screen-px";
+    readonly precision: "screen-space-approximate";
+    readonly requiredUpstreamFact: "L04 page/frame mapping";
+  };
+  readonly documents: readonly WordLayoutV2LineGeometryDocumentSummary[];
+}
+
+export function summarizeWordLayoutV2LineGeometryIntake(input: {
+  readonly generatedAtUtc: string;
+  readonly documents: readonly WordLayoutV2LineIntakeDocumentInput[];
+}): WordLayoutV2LineGeometryIntakeSummary {
+  const documents = input.documents
+    .map(summarizeDocument)
+    .sort((a, b) =>
+      a.lane.localeCompare(b.lane) ||
+      a.docId.localeCompare(b.docId) ||
+      a.recordPath?.localeCompare(b.recordPath ?? "") ||
+      0,
+    );
+  const sourceRuns = summarizeRuns(documents);
+  return {
+    schemaVersion: "layer-05-word-layout-v2-line-geometry-intake/v0",
+    generatedAtUtc: input.generatedAtUtc,
+    sourceRuns,
+    totals: {
+      documents: documents.length,
+      lineRows: sum(documents, (doc) => doc.lineBoxSummary.lineRows),
+      linesWithRects: sum(documents, (doc) => doc.lineBoxSummary.linesWithRects),
+      rectCount: sum(documents, (doc) => doc.lineBoxSummary.rectCount),
+      approxTwipsRectCount: sum(documents, (doc) => doc.lineBoxSummary.approxTwipsRectCount),
+      cleanDocuments: documents.filter((doc) => doc.lane === "ccep").length,
+      redlineDocuments: documents.filter((doc) => doc.lane === "ccep-redline").length,
+      cleanLineRows: sum(
+        documents.filter((doc) => doc.lane === "ccep"),
+        (doc) => doc.lineBoxSummary.lineRows,
+      ),
+      redlineLineRows: sum(
+        documents.filter((doc) => doc.lane === "ccep-redline"),
+        (doc) => doc.lineBoxSummary.lineRows,
+      ),
+    },
+    routing: {
+      routedTo: "L05",
+      axis: "line-geometry",
+      sourceId: "word-layout-v2.uia.lineBoxes.lines",
+      coordinateSpace: "screen-px",
+      precision: "screen-space-approximate",
+      requiredUpstreamFact: "L04 page/frame mapping",
+    },
+    documents,
+  };
+}
+
+function summarizeDocument(
+  input: WordLayoutV2LineIntakeDocumentInput,
+): WordLayoutV2LineGeometryDocumentSummary {
+  const artifact = record(input.artifact);
+  const source = record(artifact.source);
+  const tuple = record(artifact.tuple);
+  const word = record(artifact.word);
+  const comProbe = record(artifact.comProbe);
+  const uia = record(artifact.uia);
+  const lineBoxes = record(uia.lineBoxes);
+  const documentRange = record(lineBoxes.documentRange);
+  const lines = array(lineBoxes.lines);
+  const lineRows = lines.map(normalizeLineRow);
+  const lineCount = numberValue(lineBoxes.lineCount) ?? lineRows.length;
+  const rectCount = sum(lineRows, (line) => line.rects.length);
+  return {
+    lane: input.lane,
+    runId: input.runId,
+    docId: input.docId,
+    recordPath: input.recordPath,
+    source: {
+      fileName: stringValue(source.fileName),
+      sha256: stringValue(source.sha256),
+      bytes: numberValue(source.bytes),
+    },
+    tuple: {
+      zoom: numberValue(tuple.zoom),
+      viewportWidth: numberValue(tuple.viewportWidth),
+      markupMode: stringValue(tuple.markupMode),
+      dpi: numberValue(tuple.dpi),
+    },
+    word: {
+      version: stringValue(word.version),
+      build: stringValue(word.build),
+      activePrinter: stringValue(word.activePrinter),
+    },
+    comSummary: {
+      pageCount: nullableNumberValue(comProbe.pageCount),
+      paragraphCount: numberValue(comProbe.paragraphs),
+      revisionCount: numberValue(comProbe.revisions),
+      commentCount: numberValue(comProbe.comments),
+    },
+    lineBoxSummary: {
+      status: stringValue(lineBoxes.status),
+      lineCount,
+      lineRows: lineRows.length,
+      linesWithTextHash: lineRows.filter((line) => line.textHash !== undefined).length,
+      linesWithRects: lineRows.filter((line) => line.rects.length > 0).length,
+      rectCount,
+      approxTwipsRectCount: sum(
+        lineRows,
+        (line) => line.rects.filter((rect) => rect.approxTwips !== undefined).length,
+      ),
+      documentRangeRectCount: Array.isArray(documentRange.rects)
+        ? documentRange.rects.length
+        : undefined,
+      firstLineId: lineRows[0]?.lineId,
+      lastLineId: lineRows[lineRows.length - 1]?.lineId,
+      coordinateSpace: "screen-px",
+      precision: "screen-space-approximate",
+      normalizationStatus: "awaiting-l04-page-frame-join",
+    },
+    lineRows,
+  };
+}
+
+function summarizeRuns(
+  documents: readonly WordLayoutV2LineGeometryDocumentSummary[],
+): WordLayoutV2LineGeometryIntakeSummary["sourceRuns"] {
+  const keys = [...new Set(documents.map((doc) => `${doc.lane}\0${doc.runId}`))].sort();
+  return keys.map((key) => {
+    const [lane, runId] = key.split("\0") as [WordLayoutV2LineIntakeLane, string];
+    const docs = documents.filter((doc) => doc.lane === lane && doc.runId === runId);
+    const markupModes = [
+      ...new Set(docs.map((doc) => doc.tuple.markupMode).filter((mode): mode is string => !!mode)),
+    ].sort();
+    return {
+      runId,
+      lane,
+      documents: docs.length,
+      lineRows: sum(docs, (doc) => doc.lineBoxSummary.lineRows),
+      linesWithRects: sum(docs, (doc) => doc.lineBoxSummary.linesWithRects),
+      rectCount: sum(docs, (doc) => doc.lineBoxSummary.rectCount),
+      markupModes,
+    };
+  });
+}
+
+function normalizeLineRow(raw: unknown): WordLayoutV2LineGeometryRow {
+  const line = record(raw);
+  const rects = normalizeRects(line.rects);
+  return {
+    lineId: stringValue(line.lineId),
+    textHash: stringValue(line.textHash),
+    charLength: numberValue(line.charLength),
+    rectCount: numberValue(line.rectCount) ?? rects.length,
+    rects,
+  };
+}
+
+function normalizeRects(raw: unknown): readonly WordLayoutV2LineGeometryRect[] {
+  if (Array.isArray(raw)) return raw.map(normalizeRect).filter(isRect);
+  const maybeRect = normalizeRect(raw);
+  return isRect(maybeRect) ? [maybeRect] : [];
+}
+
+function normalizeRect(raw: unknown): WordLayoutV2LineGeometryRect | 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 isRect(value: WordLayoutV2LineGeometryRect | undefined): value is WordLayoutV2LineGeometryRect {
+  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 sum<T>(items: readonly T[], read: (item: T) => number): number {
+  return items.reduce((total, item) => total + read(item), 0);
+}

package/src/runtime/layout/index.ts

@@ -183,14 +183,20 @@ export {
   type PublicLineBox,
   type PublicNoteAllocation,
   type PublicPageAnchor,
+  type PublicPageFrame,
+  type PublicPageLocalStoryInstance,
   type PublicPageSpan,
   type PublicSectionNode,
   type PublicResolvedPageStories,
+  type PublicResolvedStoryField,
   type PublicResolvedParagraphFormatting,
   type PublicResolvedRunFormatting,
+  type PublicStoryAnchoredObject,
+  type PublicTwipsRect,
   type PublicBlockMeasurement,
   type PublicMeasurementFidelity,
   type PublicFieldDirtinessReport,
+  type PublicLayoutDivergence,
   type LayoutFacetEvent,
   type LayoutFacetInvalidationReason,
   type RenderZoomSummary,

package/src/runtime/layout/layout-engine-instance.ts

@@ -27,6 +27,7 @@ import type {
 import type {
   CanonicalDocumentEnvelope,
 } from "../../core/state/editor-state.ts";
+import { collectCanonicalFieldRegionIdentities } from "../../model/canonical-layout-inputs.ts";
 import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
 import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
 import {
@@ -36,7 +37,7 @@ import {
 } from "../document-layout.ts";
 import { findNoteReferencePosition } from "../view-state.ts";
 import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
-import { buildHeadingOutline } from "../document-navigation.ts";
+import { buildHeadingOutline } from "../document-heading-outline.ts";
 import {
   analyzeInvalidation,
   computeFieldDirtiness,
@@ -456,6 +457,7 @@ export function createLayoutEngine(
       MAIN_STORY_TARGET,
     );
     const sections = buildResolvedSections(document);
+    const fieldRegions = collectCanonicalFieldRegionIdentities(document);
     const pageStack = buildPageStackWithSplits(
       document,
       sections,
@@ -470,6 +472,7 @@ export function createLayoutEngine(
       pageStack.splits,
       pageStack.columnByBlockIdByPageIndex,
       pageStack.fragmentMeasurementsByPageIndex,
+      fieldRegions,
     );
     const lineBoxesByPageIndex = projectLineBoxesForPageFragments(
       pages,
@@ -642,6 +645,7 @@ export function createLayoutEngine(
         : undefined;
 
     const freshStories = resolvePageStories(freshSnapshotsToRebuild);
+    const fieldRegions = collectCanonicalFieldRegionIdentities(document);
     // Project fragments for the fresh tail pages, threading paragraph
     // line-range splits produced by intra-paragraph pagination.
     const freshBodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
@@ -650,6 +654,7 @@ export function createLayoutEngine(
       freshResult.splits,
       freshResult.columnByBlockIdByPageIndex,
       freshResult.fragmentMeasurementsByPageIndex,
+      fieldRegions,
     );
     const freshLineBoxesByPageIndex = projectLineBoxesForPageFragments(
       freshSnapshotsToRebuild,