@beyondwork/docx-react-component 1.0.109 → 1.0.111

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

@@ -49,6 +49,7 @@ import {
   buildPageStackFromWithSplits,
   buildPageStackWithSplits,
   type LayoutInvalidationReason,
+  type PageStackPaginationOptions,
 } from "./paginated-layout-engine.ts";
 import {
   buildPageGraph,
@@ -102,6 +103,21 @@ export interface LayoutEngineViewState {
 export interface LayoutEngineQueryInput {
   document: CanonicalDocumentEnvelope;
   viewState?: LayoutEngineViewState;
+  /**
+   * Optional page window for lazy pagination. L04 materializes this window
+   * plus its buffer and returns `unpaginated` placeholders for known pages
+   * outside it.
+   */
+  viewportPageWindow?: LayoutViewportPageWindow;
+}
+
+export interface LayoutViewportPageWindow {
+  startPageIndex: number;
+  endPageIndex: number;
+  /** Extra pages to materialize before/after the requested window. */
+  bufferPages?: number;
+  /** Optional total page estimate supplied by the viewport/runtime layer. */
+  estimatedPageCount?: number;
 }
 
 export interface LayoutEngineEvent {
@@ -227,9 +243,206 @@ interface CacheKey {
   content: CanonicalDocumentEnvelope["content"];
   styles: CanonicalDocumentEnvelope["styles"];
   subParts: CanonicalDocumentEnvelope["subParts"];
+  viewportWindowKey: string;
   // Note: view state does not invalidate the graph itself (graph is global).
 }
 
+interface NormalizedViewportPageWindow {
+  startPageIndex: number;
+  endPageIndex: number;
+  estimatedPageCount?: number;
+}
+
+const FULL_VIEWPORT_WINDOW_KEY = "full";
+const DEFAULT_VIEWPORT_PAGE_WINDOW_BUFFER = 1;
+
+function normalizeViewportPageWindow(
+  window: LayoutViewportPageWindow | undefined,
+): NormalizedViewportPageWindow | undefined {
+  if (!window) return undefined;
+  const buffer = Number.isFinite(window.bufferPages)
+    ? Math.max(0, Math.floor(window.bufferPages ?? 0))
+    : DEFAULT_VIEWPORT_PAGE_WINDOW_BUFFER;
+  const rawStart = Number.isFinite(window.startPageIndex)
+    ? Math.floor(window.startPageIndex)
+    : 0;
+  const rawEnd = Number.isFinite(window.endPageIndex)
+    ? Math.floor(window.endPageIndex)
+    : rawStart;
+  const startPageIndex = Math.max(0, Math.min(rawStart, rawEnd) - buffer);
+  const endPageIndex = Math.max(
+    startPageIndex,
+    Math.max(rawStart, rawEnd) + buffer,
+  );
+  const estimatedPageCount =
+    window.estimatedPageCount !== undefined && Number.isFinite(window.estimatedPageCount)
+      ? Math.max(0, Math.floor(window.estimatedPageCount))
+      : undefined;
+  return {
+    startPageIndex,
+    endPageIndex,
+    ...(estimatedPageCount !== undefined ? { estimatedPageCount } : {}),
+  };
+}
+
+function viewportWindowKey(
+  window: NormalizedViewportPageWindow | undefined,
+): string {
+  if (!window) return FULL_VIEWPORT_WINDOW_KEY;
+  return [
+    "window",
+    window.startPageIndex,
+    window.endPageIndex,
+    window.estimatedPageCount ?? "unknown",
+  ].join(":");
+}
+
+function pageStackOptionsForWindow(
+  window: NormalizedViewportPageWindow | undefined,
+): PageStackPaginationOptions | undefined {
+  if (!window) return undefined;
+  return { maxPageCount: window.endPageIndex + 1 };
+}
+
+function applyViewportWindowMaterialization(
+  graph: RuntimePageGraph,
+  window: NormalizedViewportPageWindow | undefined,
+  priorGraph: RuntimePageGraph | null,
+): RuntimePageGraph {
+  if (!window) {
+    return graph.materialization?.kind === "complete"
+      ? graph
+      : { ...graph, materialization: { kind: "complete" } };
+  }
+
+  const estimatedPageCount = Math.max(
+    graph.pages.length,
+    window.endPageIndex + 1,
+    window.estimatedPageCount ?? 0,
+    priorGraph?.pages.length ?? 0,
+  );
+  const hiddenPageIds = new Set<string>();
+  const pages: RuntimePageNode[] = graph.pages.map((page) => {
+    const materialized =
+      page.pageIndex >= window.startPageIndex &&
+      page.pageIndex <= window.endPageIndex;
+    if (materialized) {
+      return { ...page, materialization: "paginated" };
+    }
+    hiddenPageIds.add(page.pageId);
+    return toUnpaginatedPlaceholder(page);
+  });
+
+  const seed = pages[pages.length - 1] ?? graph.pages[graph.pages.length - 1];
+  if (seed) {
+    for (let pageIndex = pages.length; pageIndex < estimatedPageCount; pageIndex += 1) {
+      const placeholder = createTrailingUnpaginatedPlaceholder(
+        graph.revision,
+        pageIndex,
+        seed,
+      );
+      hiddenPageIds.add(placeholder.pageId);
+      pages.push(placeholder);
+    }
+  }
+
+  const fragments = graph.fragments.filter((fragment) => !hiddenPageIds.has(fragment.pageId));
+  const anchors = graph.anchors.filter((anchor) => !hiddenPageIds.has(anchor.pageId));
+
+  return {
+    ...graph,
+    pages,
+    fragments,
+    anchors,
+    contentPageCount: pages.filter((page) => !page.isBlankFiller).length,
+    materialization: {
+      kind: "viewport-window",
+      requestedWindow: {
+        startPageIndex: window.startPageIndex,
+        endPageIndex: window.endPageIndex,
+      },
+      paginatedRange: {
+        startPageIndex: window.startPageIndex,
+        endPageIndex: Math.min(window.endPageIndex, Math.max(0, graph.pages.length - 1)),
+      },
+      estimatedPageCount,
+    },
+  };
+}
+
+function toUnpaginatedPlaceholder(page: RuntimePageNode): RuntimePageNode {
+  const { frame: _frame, divergences: _divergences, ...rest } = page;
+  void _frame;
+  void _divergences;
+  return {
+    ...rest,
+    regions: buildUnpaginatedRegions(page.layout),
+    lineBoxes: [],
+    noteAllocations: [],
+    materialization: "unpaginated",
+  };
+}
+
+function createTrailingUnpaginatedPlaceholder(
+  revision: number,
+  pageIndex: number,
+  seed: RuntimePageNode,
+): RuntimePageNode {
+  const displayPageNumber =
+    seed.stories.displayPageNumber + Math.max(0, pageIndex - seed.pageIndex);
+  return {
+    pageId: `page-${revision}-${pageIndex}`,
+    pageIndex,
+    sectionIndex: seed.sectionIndex,
+    pageInSection:
+      seed.pageInSection >= 0
+        ? seed.pageInSection + Math.max(0, pageIndex - seed.pageIndex)
+        : pageIndex,
+    startOffset: seed.endOffset,
+    endOffset: seed.endOffset,
+    layout: seed.layout,
+    stories: {
+      ...seed.stories,
+      isFirstPage: false,
+      isEvenPage: displayPageNumber % 2 === 0,
+      displayPageNumber,
+    },
+    regions: buildUnpaginatedRegions(seed.layout),
+    lineBoxes: [],
+    noteAllocations: [],
+    isBlankFiller: false,
+    materialization: "unpaginated",
+  };
+}
+
+function buildUnpaginatedRegions(
+  layout: PageLayoutSnapshot,
+): RuntimePageNode["regions"] {
+  const bodyWidth = Math.max(
+    0,
+    layout.pageWidth - layout.marginLeft - layout.marginRight - layout.gutter,
+  );
+  const bodyHeight = Math.max(
+    0,
+    layout.pageHeight - layout.marginTop - layout.marginBottom,
+  );
+  return {
+    body: {
+      kind: "body",
+      originTwips: layout.marginTop,
+      widthTwips: bodyWidth,
+      heightTwips: bodyHeight,
+      fragmentIds: [],
+      rectTwips: {
+        xTwips: layout.marginLeft,
+        yTwips: layout.marginTop,
+        widthTwips: bodyWidth,
+        heightTwips: bodyHeight,
+      },
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Perf-probe helper (§6 E.7)
 // ---------------------------------------------------------------------------
@@ -451,6 +664,7 @@ export function createLayoutEngine(
     const recomputeStart = telemetryOn ? telemetryNow() : 0;
     const pageCountBeforeRecompute = previousPageCount;
     const document = input.document;
+    const viewportWindow = normalizeViewportPageWindow(input.viewportPageWindow);
     const mainSurface = createEditorSurfaceSnapshot(
       document,
       createSelectionSnapshot(0, 0),
@@ -463,6 +677,7 @@ export function createLayoutEngine(
       sections,
       mainSurface,
       measurementProvider,
+      pageStackOptionsForWindow(viewportWindow),
     );
     const pages = pageStack.pages;
     const stories = resolvePageStories(pages);
@@ -478,6 +693,7 @@ export function createLayoutEngine(
       pages,
       bodyFragmentsByPageIndex,
       pageStack.fragmentMeasurementsByPageIndex,
+      mainSurface,
     );
     // P8.1b — merge per-note fragments (regionKind: "footnote-area") into the
     // main fragments map so buildPageGraph sees them alongside body fragments.
@@ -486,7 +702,7 @@ export function createLayoutEngine(
       const existing = fragmentsByPageIndex.get(pageIndex) ?? [];
       fragmentsByPageIndex.set(pageIndex, [...existing, ...noteFragments]);
     }
-    const graph = buildPageGraph({
+    const measuredGraph = buildPageGraph({
       pages,
       sections,
       stories,
@@ -495,6 +711,11 @@ export function createLayoutEngine(
       noteAllocationsByPageIndex: pageStack.noteAllocationsByPageIndex,
       subParts: document.subParts,
     });
+    const graph = applyViewportWindowMaterialization(
+      measuredGraph,
+      viewportWindow,
+      cachedGraph,
+    );
 
     // Field dirtiness diff from previous graph
     const dirtyFamilies = computeFieldDirtiness(cachedGraph, graph);
@@ -504,7 +725,7 @@ export function createLayoutEngine(
 
     const formatting = buildResolvedFormattingState(document, mainSurface);
 
-    const currentPageCount = resolveTotalPageCount(pages);
+    const currentPageCount = graph.contentPageCount;
     // Compute the delta only; `previousPageCount` is mutated AFTER all
     // emits so every emission reads the pre-commit value through the
     // `pageCountDelta` local. `incrementalRelayout` mirrors this order
@@ -520,6 +741,7 @@ export function createLayoutEngine(
       content: document.content,
       styles: document.styles,
       subParts: document.subParts,
+      viewportWindowKey: viewportWindowKey(viewportWindow),
     };
     cachedGraph = graph;
     cachedFormatting = formatting;
@@ -660,6 +882,7 @@ export function createLayoutEngine(
       freshSnapshotsToRebuild,
       freshBodyFragmentsByPageIndex,
       freshResult.fragmentMeasurementsByPageIndex,
+      mainSurface,
     );
     // P8.1b — merge per-note fragments into the fresh fragments map.
     const freshFragmentsByPageIndex = new Map(freshBodyFragmentsByPageIndex);
@@ -752,6 +975,7 @@ export function createLayoutEngine(
       content: document.content,
       styles: document.styles,
       subParts: document.subParts,
+      viewportWindowKey: FULL_VIEWPORT_WINDOW_KEY,
     };
     cachedGraph = splicedGraph;
     cachedFormatting = formatting;
@@ -780,12 +1004,15 @@ export function createLayoutEngine(
 
   function getGraphInternal(input: LayoutEngineQueryInput): RuntimePageGraph {
     const document = input.document;
+    const normalizedWindow = normalizeViewportPageWindow(input.viewportPageWindow);
+    const currentViewportWindowKey = viewportWindowKey(normalizedWindow);
     const keyEqual =
       cachedGraph !== null &&
       cachedKey !== null &&
       cachedKey.content === document.content &&
       cachedKey.styles === document.styles &&
-      cachedKey.subParts === document.subParts;
+      cachedKey.subParts === document.subParts &&
+      cachedKey.viewportWindowKey === currentViewportWindowKey;
 
     if (keyEqual && pendingInvalidation === null) {
       return cachedGraph!;
@@ -797,7 +1024,8 @@ export function createLayoutEngine(
     if (
       pending !== null &&
       pending.result.scope === "bounded" &&
-      cachedGraph !== null
+      cachedGraph !== null &&
+      normalizedWindow === undefined
     ) {
       const spliced = incrementalRelayout(input, pending);
       if (spliced !== null) {
@@ -1009,6 +1237,7 @@ export function createLayoutEngine(
         content: document.content,
         styles: document.styles,
         subParts: document.subParts,
+        viewportWindowKey: FULL_VIEWPORT_WINDOW_KEY,
       };
       previousPageCount = graph.contentPageCount;
     },

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

@@ -1233,8 +1233,49 @@
  *   history-block bumped to v81 in isolation; ship-preview's rollup advances
  *   to v87. Cache envelopes from v86 invalidate because table row ranges and
  *   continuation cursor payloads can change.
+ *
+ *  88 — Ship-side rollup: pe2 commit 327244cee ("Add L04 lazy pagination
+ *   placeholders") landed L04 lazy pagination — layout queries can now pass
+ *   a viewport page window; windowed reads bound pagination by the requested
+ *   high-water page when possible and emit `unpaginated` page placeholders
+ *   outside the materialized range. Pe2 commits 378e1b9c6 ("feat(05): consume
+ *   numbering readback joins") + 64e64567f ("feat(05): project adjacent
+ *   geometry into l04 frames") additionally brushed `src/runtime/geometry/**`,
+ *   and pe2 commit d5597ed33 ("feat(11): consume field ledgers and split row
+ *   carry") brushed `src/runtime/layout/public-facet.ts` +
+ *   `resolve-page-previews.ts`, all without separate pe2 bumps. The pe2
+ *   history-block bumped to v82 in isolation; ship-preview's rollup advances
+ *   to v88. Cache envelopes from v87 invalidate because page graph
+ *   materialization state, cache-key semantics, geometry projections, and
+ *   surface preview shapes can change.
+ *
+ *  89 — Ship-side rollup: pe2 commit covering L04 pagination telemetry read
+ *   model — `WordReviewEditorLayoutFacet` now exposes
+ *   `getPaginationTelemetry()`, with per-page materialization, body-fragment
+ *   counts, body block-reference counts, line-box counts, and
+ *   materialized-page averages. Pagination output and cached graph payloads
+ *   are unchanged; cache envelopes from v88 invalidate because the public
+ *   layout facet interface grew a method used by viewport-window consumers.
+ *   The pe2 history-block bumped to v83 in isolation; ship-preview's rollup
+ *   advances to v89.
+ *
+ *  90 — Ship-side rollup: pe2 commit 2fcc15a10 ("feat(04): publish precision
+ *   producer layout facts") landed L04 precision producer facts — runtime
+ *   line boxes now carry page-local rects, baseline page coordinates,
+ *   paragraph direction, and per-run layout-estimate anchors with first/last
+ *   glyph bounds. Page-local anchored-object ledgers can carry
+ *   `anchorRectTwips` when canonical anchor metadata gives L04 a source/frame
+ *   placement. Pe2 commits a22c2e4ab ("feat(05): consume l04 producer
+ *   geometry facts") + 6e71ee2ad ("feat(05): publish frame-pixel adjacent
+ *   geometry") additionally brushed `src/runtime/geometry/**`, and pe2
+ *   commits 883e46bb7 + 8519112d0 ("fix(11): suppress table-internal page
+ *   chrome / anchors") brushed `src/runtime/layout/page-graph.ts` without
+ *   separate pe2 bumps. The pe2 history-block bumped to v84 in isolation;
+ *   ship-preview's rollup advances to v90. Pagination output is unchanged,
+ *   but public graph/read-model semantics grew for L05 exact caret/object
+ *   projection consumers and for L11 page-anchor suppression in tables.
  */
-export const LAYOUT_ENGINE_VERSION = 87 as const;
+export const LAYOUT_ENGINE_VERSION = 90 as const;
 
 /**
  * Serialization schema version for the LayCache envelope and cached payload
@@ -1275,5 +1316,9 @@ export const LAYOUT_ENGINE_VERSION = 87 as const;
  *       `numberingRows[]` for all numbered paragraphs represented by the
  *       fragment, including table/SDT-nested paragraphs. Pagination output is
  *       unchanged, but cached graph payload shape grows.
+ *   7 — L04 precision producer graph payload: line boxes carry page-local
+ *       rect/baseline/direction/run-anchor facts, and page-local anchored
+ *       object ledgers can carry source-anchor `anchorRectTwips`. Pagination
+ *       output is unchanged, but cached graph payload shape grows.
  */
-export const LAYCACHE_SCHEMA_VERSION = 6 as const;
+export const LAYCACHE_SCHEMA_VERSION = 7 as const;

package/src/runtime/layout/layout-facet-types.ts

@@ -42,11 +42,14 @@ export type {
   PublicRegionKind,
   PublicBlockFragment,
   PublicLineBox,
+  PublicLineRunAnchor,
   PublicNoteAllocation,
   PublicPageAnchor,
   PublicPageFrame,
   PublicPageLocalStoryInstance,
+  PublicPagePaginationTelemetry,
   PublicPageSpan,
+  PublicPaginationTelemetry,
   PublicSectionNode,
   PublicResolvedPageStories,
   PublicResolvedStoryField,

package/src/runtime/layout/page-graph.ts

@@ -77,12 +77,16 @@ export type {
   RuntimeFragmentLayoutObject,
   RuntimeBlockFragment,
   RuntimeLineBox,
+  RuntimeLineRunAnchor,
   RuntimeNoteAllocation,
   RuntimePageAnchor,
 } from "../../model/layout/page-graph-types.ts";
 
 export type {
   RuntimePageGraph,
+  RuntimePageGraphMaterialization,
+  RuntimePageMaterialization,
+  RuntimePageWindowRange,
   RuntimePageNode,
   BuildPageGraphInput,
 } from "../../model/layout/runtime-page-graph-types.ts";
@@ -253,6 +257,7 @@ export function buildPageGraph(
         [],
       noteAllocations: pageNoteAllocations,
       isBlankFiller: page.pageInSection === -1,
+      materialization: "paginated",
     };
     pages.push(node);
 
@@ -562,6 +567,7 @@ function buildPageLocalStoryInstance(
         kind: target.kind,
         variant: target.variant,
         relationshipId: target.relationshipId,
+        region,
       })
     : { objects: [], divergences: [] };
   const signature = buildPageLocalStorySignature({
@@ -617,6 +623,10 @@ function buildPageLocalStorySignature(input: {
         object.display,
         object.extentTwips?.widthTwips ?? "",
         object.extentTwips?.heightTwips ?? "",
+        object.anchorRectTwips?.xTwips ?? "",
+        object.anchorRectTwips?.yTwips ?? "",
+        object.anchorRectTwips?.widthTwips ?? "",
+        object.anchorRectTwips?.heightTwips ?? "",
         object.relationshipIds?.join(",") ?? "",
         object.mediaIds?.join(",") ?? "",
         object.wrapMode ?? "",
@@ -728,6 +738,7 @@ interface StoryObjectContext {
   kind: "header" | "footer";
   variant: RuntimePageLocalStoryInstance["variant"];
   relationshipId: string;
+  region?: RuntimePageRegion;
 }
 
 function collectStoryAnchoredObjects(
@@ -832,13 +843,20 @@ function collectStoryAnchoredObjects(
         const preserveHint = getDrawingFramePreserveHint(inline);
         const relationshipIds = collectDrawingRelationshipIds(inline);
         const display = inline.anchor.display;
+        const extentTwips = extentTwipsFromEmu(
+          inline.anchor.extent.widthEmu,
+          inline.anchor.extent.heightEmu,
+        );
         pushObject({
           objectId: getDrawingFrameObjectId(inline, context.storyKey, ordinal),
           sourceType: "drawing-frame",
           display,
-          extentTwips: extentTwipsFromEmu(
-            inline.anchor.extent.widthEmu,
-            inline.anchor.extent.heightEmu,
+          extentTwips,
+          anchorRectTwips: resolveObjectAnchorRectTwips(
+            context.region,
+            extentTwips,
+            inline.anchor.positionH,
+            inline.anchor.positionV,
           ),
           ...(relationshipIds.length > 0 ? { relationshipIds } : {}),
           ...(inline.content.type === "picture" && inline.content.mediaId
@@ -859,15 +877,22 @@ function collectStoryAnchoredObjects(
       case "wordart":
       case "vml_shape": {
         const preserveHint = inline.preserveOnlyObject;
+        const extentTwips = preserveHint?.extentEmu
+          ? extentTwipsFromEmu(
+              preserveHint.extentEmu.widthEmu,
+              preserveHint.extentEmu.heightEmu,
+            )
+          : undefined;
         pushObject({
           objectId: getPreserveOnlyObjectId(inline, context.storyKey, ordinal),
           sourceType: sourceTypeForInlineObject(inline.type),
           display: preserveHint?.display ?? "unknown",
-          ...(preserveHint?.extentEmu
+          ...(extentTwips
             ? {
-                extentTwips: extentTwipsFromEmu(
-                  preserveHint.extentEmu.widthEmu,
-                  preserveHint.extentEmu.heightEmu,
+                extentTwips,
+                anchorRectTwips: resolveObjectAnchorRectTwips(
+                  context.region,
+                  extentTwips,
                 ),
               }
             : {}),
@@ -982,6 +1007,59 @@ function extentTwipsFromEmu(
   };
 }
 
+function resolveObjectAnchorRectTwips(
+  region: RuntimePageRegion | undefined,
+  extentTwips: RuntimeStoryAnchoredObject["extentTwips"],
+  positionH?: { relativeFrom: string; align?: string; offset?: number },
+  positionV?: { relativeFrom: string; align?: string; offset?: number },
+): RuntimeTwipsRect | undefined {
+  if (!region?.rectTwips || !extentTwips) return undefined;
+  const regionRect = region.rectTwips;
+  const widthTwips = Math.max(0, extentTwips.widthTwips);
+  const heightTwips = Math.max(0, extentTwips.heightTwips);
+  return rect(
+    resolveAxisTwips(
+      regionRect.xTwips,
+      regionRect.widthTwips,
+      widthTwips,
+      positionH?.align,
+      positionH?.offset,
+    ),
+    resolveAxisTwips(
+      regionRect.yTwips,
+      regionRect.heightTwips,
+      heightTwips,
+      positionV?.align,
+      positionV?.offset,
+    ),
+    widthTwips,
+    heightTwips,
+  );
+}
+
+function resolveAxisTwips(
+  originTwips: number,
+  spanTwips: number,
+  objectSpanTwips: number,
+  align?: string,
+  offsetEmu?: number,
+): number {
+  if (offsetEmu !== undefined) {
+    return originTwips + Math.round(offsetEmu / EMUS_PER_TWIP);
+  }
+  switch (align) {
+    case "center":
+      return originTwips + Math.round((spanTwips - objectSpanTwips) / 2);
+    case "right":
+    case "bottom":
+      return originTwips + Math.max(0, spanTwips - objectSpanTwips);
+    case "left":
+    case "top":
+    default:
+      return originTwips;
+  }
+}
+
 function resolvePageInstanceFieldDisplayText(
   family: string,
   cachedDisplayText: string,
@@ -1390,6 +1468,9 @@ function pageNodesStructurallyEqual(
   if (a.startOffset !== b.startOffset) return false;
   if (a.endOffset !== b.endOffset) return false;
   if (a.isBlankFiller !== b.isBlankFiller) return false;
+  if ((a.materialization ?? "paginated") !== (b.materialization ?? "paginated")) {
+    return false;
+  }
   if (a.regions.body.fragmentIds.length !== b.regions.body.fragmentIds.length) {
     return false;
   }