@beyondwork/docx-react-component 1.0.109 → 1.0.110

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

@@ -106,6 +106,7 @@ export function projectGeometryIndexFromFrame(
   let splitRowCarryCount = 0;
 
   for (const page of frame.pages) {
+    if (!isPageGeometryMaterialized(page)) continue;
     const pageMetadata = pageFrameMetadata(page);
     pageFrameCompleteness[pageMetadata.frameCompleteness] += 1;
     layoutDivergenceObjectCount += pageMetadata.layoutDivergenceObjectIds.length;
@@ -313,7 +314,7 @@ export function projectGeometryIndexFromFrame(
 
   const objectHandles = finalizeObjectHandleEntries(objectHandleEntries);
   const coverage: GeometryIndexCoverage = {
-    status: "realized",
+    status: coverageStatusForProjectedPages(frame, pages.length),
     pageCount: pages.length,
     pageFrameCompleteness,
     regionCount: regions.length,
@@ -367,6 +368,7 @@ export function summarizeGeometryCoverageFromFrame(
   let splitRowCarryCount = 0;
 
   for (const page of frame.pages) {
+    if (!isPageGeometryMaterialized(page)) continue;
     const pageMetadata = pageFrameMetadata(page);
     pageCount += 1;
     pageFrameCompleteness[pageMetadata.frameCompleteness] += 1;
@@ -407,7 +409,7 @@ export function summarizeGeometryCoverageFromFrame(
   }
 
   return {
-    status: "realized",
+    status: coverageStatusForProjectedPages(frame, pageCount),
     pageCount,
     pageFrameCompleteness,
     regionCount,
@@ -433,6 +435,19 @@ interface PageFrameMetadata {
   divergenceIdsByObjectId: ReadonlyMap<string, readonly string[]>;
 }
 
+function isPageGeometryMaterialized(page: RenderPage): boolean {
+  return page.page.materialization !== "unpaginated";
+}
+
+function coverageStatusForProjectedPages(
+  frame: RenderFrame,
+  projectedPageCount: number,
+): GeometryRehydrationStatus {
+  return frame.pages.length > 0 && projectedPageCount === 0
+    ? "unavailable"
+    : "realized";
+}
+
 function pageFrameMetadata(page: RenderPage): PageFrameMetadata {
   const frame = page.page.frame;
   const divergenceIds = frame?.divergenceIds ? [...frame.divergenceIds] : [];

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);
@@ -486,7 +701,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 +710,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 +724,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 +740,7 @@ export function createLayoutEngine(
       content: document.content,
       styles: document.styles,
       subParts: document.subParts,
+      viewportWindowKey: viewportWindowKey(viewportWindow),
     };
     cachedGraph = graph;
     cachedFormatting = formatting;
@@ -752,6 +973,7 @@ export function createLayoutEngine(
       content: document.content,
       styles: document.styles,
       subParts: document.subParts,
+      viewportWindowKey: FULL_VIEWPORT_WINDOW_KEY,
     };
     cachedGraph = splicedGraph;
     cachedFormatting = formatting;
@@ -780,12 +1002,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 +1022,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 +1235,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,23 @@
  *   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.
  */
-export const LAYOUT_ENGINE_VERSION = 87 as const;
+export const LAYOUT_ENGINE_VERSION = 88 as const;
 
 /**
  * Serialization schema version for the LayCache envelope and cached payload

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

@@ -83,6 +83,9 @@ export type {
 
 export type {
   RuntimePageGraph,
+  RuntimePageGraphMaterialization,
+  RuntimePageMaterialization,
+  RuntimePageWindowRange,
   RuntimePageNode,
   BuildPageGraphInput,
 } from "../../model/layout/runtime-page-graph-types.ts";
@@ -253,6 +256,7 @@ export function buildPageGraph(
         [],
       noteAllocations: pageNoteAllocations,
       isBlankFiller: page.pageInSection === -1,
+      materialization: "paginated",
     };
     pages.push(node);
 
@@ -1390,6 +1394,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;
   }

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

@@ -209,6 +209,14 @@ export interface PageStackResultWithSplits {
   fragmentMeasurementsByPageIndex?: ReadonlyMap<number, ReadonlyMap<string, FragmentMeasurement>>;
 }
 
+export interface PageStackPaginationOptions {
+  /**
+   * Stop after this many global pages have been emitted. Used by L04 lazy
+   * pagination so viewport reads can avoid walking the whole document tail.
+   */
+  maxPageCount?: number;
+}
+
 // ---------------------------------------------------------------------------
 // Facade
 // ---------------------------------------------------------------------------
@@ -248,6 +256,7 @@ export function buildPageStackWithSplits(
   sections: ResolvedDocumentSection[],
   mainSurface: EditorSurfaceSnapshot,
   measurementProvider?: LayoutMeasurementProvider,
+  options?: PageStackPaginationOptions,
 ): PageStackResultWithSplits {
   const defaultTabInterval = document.subParts?.settings?.defaultTabStop ?? 720;
   // Theme-font fallback for L04 dominant-font resolution. Threaded into
@@ -288,8 +297,15 @@ export function buildPageStackWithSplits(
   // reuses heights.  The WeakMap frees memory automatically when the block
   // snapshots go out of scope at the end of the call.
   const cache = createMeasurementCache();
+  const maxPageCount =
+    options?.maxPageCount !== undefined
+      ? Math.max(1, Math.floor(options.maxPageCount))
+      : undefined;
+  const hasReachedMaxPageCount = (): boolean =>
+    maxPageCount !== undefined && globalPageIndex >= maxPageCount;
 
   for (let sectionIdx = 0; sectionIdx < sections.length; sectionIdx++) {
+    if (hasReachedMaxPageCount()) break;
     const section = sections[sectionIdx]!;
     const layout = buildPageLayoutSnapshot(
       section.index,
@@ -347,6 +363,7 @@ export function buildPageStackWithSplits(
 
     if (breakType === "evenPage" && globalPageIndex > 0) {
       if (nextDisplayPage % 2 !== 0) {
+        if (hasReachedMaxPageCount()) break;
         const prevLayout = pages[pages.length - 1]?.layout ?? layout;
         pages.push({
           pageIndex: globalPageIndex,
@@ -360,6 +377,7 @@ export function buildPageStackWithSplits(
       }
     } else if (breakType === "oddPage" && globalPageIndex > 0) {
       if (nextDisplayPage % 2 === 0) {
+        if (hasReachedMaxPageCount()) break;
         const prevLayout = pages[pages.length - 1]?.layout ?? layout;
         pages.push({
           pageIndex: globalPageIndex,
@@ -383,6 +401,9 @@ export function buildPageStackWithSplits(
       defaultTabInterval,
       nextColumnSeed,
       themeFonts,
+      maxPageCount !== undefined
+        ? { maxPageCount: Math.max(1, maxPageCount - globalPageIndex) }
+        : undefined,
     );
     const paginated = paginatedResult.pages;
 
@@ -421,6 +442,7 @@ export function buildPageStackWithSplits(
         }
         continue;
       }
+      if (hasReachedMaxPageCount()) break;
       pageInSectionToGlobal.set(page.pageInSection, globalPageIndex);
       pages.push({
         ...page,
@@ -1612,6 +1634,7 @@ export function paginateSectionBlocksWithSplits(
    * `subParts.resolvedTheme` — threaded from `buildPageStackWithSplits`.
    */
   themeFonts?: LayoutThemeFonts,
+  options?: PageStackPaginationOptions,
 ): SectionPaginationResult {
   if (blocks.length === 0) {
     return {
@@ -1633,6 +1656,11 @@ export function paginateSectionBlocksWithSplits(
   }
 
   const pages: Omit<DocumentPageSnapshot, "pageIndex">[] = [];
+  const maxPageCount =
+    options?.maxPageCount !== undefined
+      ? Math.max(1, Math.floor(options.maxPageCount))
+      : undefined;
+  let reachedPageLimit = false;
   const splitsByBlock = new Map<string, SectionLocalSlice[]>();
   const tableSplitsByBlock = new Map<string, SectionLocalTableSlice[]>();
   const fragmentMeasurementsByPageInSection = new Map<number, Map<string, FragmentMeasurement>>();
@@ -1850,6 +1878,7 @@ export function paginateSectionBlocksWithSplits(
   };
 
   const pushPage = (endOffset: number): void => {
+    if (reachedPageLimit) return;
     const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
     if (boundedEnd === pageStart && pages.length > 0) {
       return;
@@ -1877,12 +1906,17 @@ export function paginateSectionBlocksWithSplits(
     pendingNoteKeys.clear();
     pendingNoteBlockFroms.clear();
     pendingNoteColumnWidths.clear();
+    if (maxPageCount !== undefined && pages.length >= maxPageCount) {
+      reachedPageLimit = true;
+    }
   };
 
   for (let index = 0; index < blocks.length; index += 1) {
+    if (reachedPageLimit) break;
     const block = blocks[index]!;
     const nextBoundary = blocks[index + 1]?.from ?? section.end;
     while (true) {
+      if (reachedPageLimit) break;
       const columnWidth =
         columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
         getUsableColumnWidth(layout);

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

@@ -204,6 +204,8 @@ export interface PublicPageNode {
   endOffset: number;
   /** Whether this page is a blank filler (e.g. from evenPage/oddPage). */
   isBlankFiller: boolean;
+  /** Whether L04 has measured this page or it is a lazy-pagination placeholder. */
+  materialization: NonNullable<RuntimePageNode["materialization"]>;
   /** Resolved display page number (1-based, honors section restarts). */
   displayPageNumber: number;
   /** Whether this is treated as the first page of its section (title page). */
@@ -1446,6 +1448,7 @@ function toPublicPageNode(
     startOffset: node.startOffset,
     endOffset: node.endOffset,
     isBlankFiller: node.isBlankFiller,
+    materialization: node.materialization ?? "paginated",
     displayPageNumber: node.stories.displayPageNumber,
     isFirstPage: node.stories.isFirstPage,
     isEvenPage: node.stories.isEvenPage,
@@ -2178,6 +2181,10 @@ function resolveHeaderFooterRegionBlocks(
         blockSnapshot,
         node,
         graph,
+        {
+          ledger: findPageLocalStoryFieldLedger(node, regionKind, storyTarget),
+          ordinal: 0,
+        },
       );
       return {
         blockId: blockSnapshot.blockId,
@@ -2201,6 +2208,33 @@ const PAGE_INSTANCE_FIELD_FAMILIES = new Set([
   "SECTIONPAGES",
 ]);
 
+type PageLocalFieldLedger = readonly {
+  readonly family: string;
+  readonly displayText: string;
+}[];
+
+interface PageScopedFieldState {
+  readonly ledger: PageLocalFieldLedger | undefined;
+  ordinal: number;
+}
+
+function findPageLocalStoryFieldLedger(
+  page: RuntimePageNode,
+  regionKind: "header" | "footer",
+  storyTarget: EditorStoryTarget,
+): PageLocalFieldLedger | undefined {
+  if (storyTarget.kind !== regionKind) return undefined;
+  const pageLocalStory = page.frame?.pageLocalStories.find(
+    (story) =>
+      story.kind === storyTarget.kind &&
+      story.relationshipId === storyTarget.relationshipId &&
+      story.variant === storyTarget.variant &&
+      (storyTarget.sectionIndex === undefined ||
+        story.sectionIndex === storyTarget.sectionIndex),
+  );
+  return pageLocalStory?.resolvedFields;
+}
+
 function resolvePageScopedFieldsInBlocks(
   blocks: readonly SurfaceBlockSnapshot[],
   page: RuntimePageNode,
@@ -2208,7 +2242,10 @@ function resolvePageScopedFieldsInBlocks(
 ): readonly SurfaceBlockSnapshot[] {
   let changed = false;
   const resolvedBlocks = blocks.map((block) => {
-    const resolved = resolvePageInstanceFieldsInBlock(block, page, graph);
+    const resolved = resolvePageInstanceFieldsInBlock(block, page, graph, {
+      ledger: undefined,
+      ordinal: 0,
+    });
     if (resolved !== block) changed = true;
     return resolved;
   });
@@ -2219,10 +2256,16 @@ function resolvePageInstanceFieldsInBlock(
   block: SurfaceBlockSnapshot,
   page: RuntimePageNode,
   graph: RuntimePageGraph,
+  fieldState: PageScopedFieldState,
 ): SurfaceBlockSnapshot {
   switch (block.kind) {
     case "paragraph": {
-      const segments = resolvePageInstanceFieldsInSegments(block.segments, page, graph);
+      const segments = resolvePageInstanceFieldsInSegments(
+        block.segments,
+        page,
+        graph,
+        fieldState,
+      );
       return segments === block.segments ? block : { ...block, segments };
     }
     case "table": {
@@ -2232,7 +2275,12 @@ function resolvePageInstanceFieldsInBlock(
         const cells = row.cells.map((cell) => {
           let cellChanged = false;
           const content = cell.content.map((child) => {
-            const resolved = resolvePageInstanceFieldsInBlock(child, page, graph);
+            const resolved = resolvePageInstanceFieldsInBlock(
+              child,
+              page,
+              graph,
+              fieldState,
+            );
             if (resolved !== child) cellChanged = true;
             return resolved;
           });
@@ -2249,7 +2297,12 @@ function resolvePageInstanceFieldsInBlock(
     case "sdt_block": {
       let changed = false;
       const children = block.children.map((child) => {
-        const resolved = resolvePageInstanceFieldsInBlock(child, page, graph);
+        const resolved = resolvePageInstanceFieldsInBlock(
+          child,
+          page,
+          graph,
+          fieldState,
+        );
         if (resolved !== child) changed = true;
         return resolved;
       });
@@ -2264,17 +2317,23 @@ function resolvePageInstanceFieldsInSegments(
   segments: SurfaceInlineSegment[],
   page: RuntimePageNode,
   graph: RuntimePageGraph,
+  fieldState: PageScopedFieldState,
 ): SurfaceInlineSegment[] {
   let changed = false;
   const resolvedSegments = segments.map((segment) => {
     if (segment.kind !== "field_ref" || !PAGE_INSTANCE_FIELD_FAMILIES.has(segment.fieldFamily)) {
       return segment;
     }
-    const displayText = resolvePageFieldDisplayText(
-      segment.fieldFamily,
-      segment.displayText ?? segment.label,
-      { page, graph },
-    );
+    const ledgerField = fieldState.ledger?.[fieldState.ordinal];
+    fieldState.ordinal += 1;
+    const displayText =
+      ledgerField?.family === segment.fieldFamily
+        ? ledgerField.displayText
+        : resolvePageFieldDisplayText(
+            segment.fieldFamily,
+            segment.displayText ?? segment.label,
+            { page, graph },
+          );
     if (segment.displayText === displayText && segment.refreshStatus === "current") {
       return segment;
     }