@beyondwork/docx-react-component 1.0.40 → 1.0.42

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

@@ -63,6 +63,12 @@ import {
 import { analyzeInvalidation as analyzeInvalidationFn } from "./layout-invalidation.ts";
 import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
 import { paginateParagraphLines } from "./paginate-paragraph-lines.ts";
+import {
+  computeRepeatedHeaderHeight,
+  extractRowFlags,
+  findTableRowSplit,
+  measureTableRowHeights,
+} from "./table-row-split.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -177,6 +183,11 @@ export function buildPageStackWithSplits(
   const pages: DocumentPageSnapshot[] = [];
   const splitsByBlock = new Map<string, ParagraphLineSlice[]>();
   let globalPageIndex = 0;
+  // A single cache lives for the whole pagination pass so cross-section
+  // re-measurement (rare but possible through keepNext heuristics) still
+  // reuses heights.  The WeakMap frees memory automatically when the block
+  // snapshots go out of scope at the end of the call.
+  const cache = createMeasurementCache();
 
   for (let sectionIdx = 0; sectionIdx < sections.length; sectionIdx++) {
     const section = sections[sectionIdx]!;
@@ -234,6 +245,7 @@ export function buildPageStackWithSplits(
       layout,
       document.subParts?.footnoteCollection,
       measurementProvider,
+      cache,
     );
     const paginated = paginatedResult.pages;
 
@@ -560,6 +572,59 @@ export function requiresFullRecompute(reason: LayoutInvalidationReason): boolean
 const MIN_BLOCK_HEIGHT_TWIPS = 240;
 const FOOTNOTE_REFERENCE_RESERVATION_TWIPS = 180;
 
+/**
+ * Per-invocation measurement cache keyed by `(block, columnWidth)`.
+ *
+ * Pagination re-measures the same block more than once in the hot path:
+ * - `keepNext` checks both the current and the next block's height
+ * - Intra-paragraph splits re-ask for `measureParagraphLineCount`
+ * - Multi-pass pagination (splitRule, column advance) may loop over the
+ *   same block with the same column width
+ *
+ * The cache is scoped to a single `buildPageStackWithSplits` call. Block
+ * references are stable during one pagination pass (the `blocks` array is
+ * frozen for the run), so a `WeakMap<Block, Map<columnWidth, height>>` is
+ * cheap and never outlives the call.
+ *
+ * Canvas-backed measurement is the expensive case; the empirical backend
+ * does its own work inline but the cache still saves redundant iteration.
+ */
+interface MeasurementCache {
+  getHeight(block: SurfaceBlockSnapshot, columnWidth: number): number | undefined;
+  setHeight(block: SurfaceBlockSnapshot, columnWidth: number, heightTwips: number): void;
+  getLineCount(block: SurfaceBlockSnapshot, columnWidth: number): number | undefined;
+  setLineCount(block: SurfaceBlockSnapshot, columnWidth: number, lineCount: number): void;
+}
+
+function createMeasurementCache(): MeasurementCache {
+  const heightByBlock = new WeakMap<SurfaceBlockSnapshot, Map<number, number>>();
+  const lineCountByBlock = new WeakMap<SurfaceBlockSnapshot, Map<number, number>>();
+  return {
+    getHeight(block, columnWidth) {
+      return heightByBlock.get(block)?.get(columnWidth);
+    },
+    setHeight(block, columnWidth, heightTwips) {
+      let map = heightByBlock.get(block);
+      if (!map) {
+        map = new Map();
+        heightByBlock.set(block, map);
+      }
+      map.set(columnWidth, heightTwips);
+    },
+    getLineCount(block, columnWidth) {
+      return lineCountByBlock.get(block)?.get(columnWidth);
+    },
+    setLineCount(block, columnWidth, lineCount) {
+      let map = lineCountByBlock.get(block);
+      if (!map) {
+        map = new Map();
+        lineCountByBlock.set(block, map);
+      }
+      map.set(columnWidth, lineCount);
+    },
+  };
+}
+
 /**
  * Compute block height using resolved formatting when available.
  * Uses improved table measurement for legal contracts.
@@ -567,42 +632,76 @@ const FOOTNOTE_REFERENCE_RESERVATION_TWIPS = 180;
  * When `measurementProvider` is supplied, paragraph line counts are produced
  * by `provider.measureLineFragments(...)`; otherwise the inline empirical
  * path runs (which matches the empirical backend numerically).
+ *
+ * When `cache` is supplied, repeated measurements of the same
+ * `(block, columnWidth)` pair short-circuit to the cached value.
  */
 function measureBlockHeight(
   block: SurfaceBlockSnapshot | undefined,
   columnWidth: number,
   measurementProvider?: LayoutMeasurementProvider,
+  cache?: MeasurementCache,
 ): number {
   if (!block) return 0;
 
-  switch (block.kind) {
-    case "paragraph": {
-      const formatting = resolveBlockFormatting(block);
-      if (formatting) {
-        const lineCount = measureParagraphLineCount(
-          block,
-          formatting,
-          columnWidth,
-          measurementProvider,
-        );
-        return calculateParagraphHeight(formatting, lineCount);
+  const cached = cache?.getHeight(block, columnWidth);
+  if (cached !== undefined) return cached;
+
+  const compute = (): number => {
+    switch (block.kind) {
+      case "paragraph": {
+        const formatting = resolveBlockFormatting(block);
+        if (formatting) {
+          // Provider path: sum per-line heights so canvas-backed measurements
+          // that emit variable line heights (mixed inline font sizes, etc.)
+          // do not collapse to `lineCount * flatLineHeight`.
+          if (measurementProvider) {
+            const measured = measurementProvider.measureLineFragments({
+              block,
+              formatting,
+              runs: new Map(),
+              columnWidth,
+            });
+            cache?.setLineCount(block, columnWidth, measured.lineCount);
+            const contentHeight = measured.lineHeights.reduce(
+              (total, lineHeight) => total + lineHeight,
+              0,
+            );
+            const paragraphHeight =
+              contentHeight + formatting.spacingBefore + formatting.spacingAfter;
+            return Math.max(MIN_BLOCK_HEIGHT_TWIPS, paragraphHeight);
+          }
+          // Empirical-fallback path: flat per-line height × count.
+          const lineCount = measureParagraphLineCount(
+            block,
+            formatting,
+            columnWidth,
+            undefined,
+          );
+          return calculateParagraphHeight(formatting, lineCount);
+        }
+        return estimateBlockHeight(block, columnWidth);
       }
-      return estimateBlockHeight(block, columnWidth);
+      case "table":
+        return measureTableHeight(block, columnWidth, measurementProvider, cache);
+      case "sdt_block":
+        return Math.max(
+          MIN_BLOCK_HEIGHT_TWIPS,
+          block.children.reduce(
+            (total, child) =>
+              total +
+              measureBlockHeight(child, columnWidth, measurementProvider, cache),
+            0,
+          ),
+        );
+      case "opaque_block":
+        return block.label === "Section break" ? 0 : MIN_BLOCK_HEIGHT_TWIPS;
     }
-    case "table":
-      return measureTableHeight(block, columnWidth, measurementProvider);
-    case "sdt_block":
-      return Math.max(
-        MIN_BLOCK_HEIGHT_TWIPS,
-        block.children.reduce(
-          (total, child) =>
-            total + measureBlockHeight(child, columnWidth, measurementProvider),
-          0,
-        ),
-      );
-    case "opaque_block":
-      return block.label === "Section break" ? 0 : MIN_BLOCK_HEIGHT_TWIPS;
-  }
+  };
+
+  const height = compute();
+  cache?.setHeight(block, columnWidth, height);
+  return height;
 }
 
 /**
@@ -621,6 +720,7 @@ function measureTableHeight(
   block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
   columnWidth: number,
   measurementProvider?: LayoutMeasurementProvider,
+  cache?: MeasurementCache,
 ): number {
   const TABLE_ROW_PADDING_TWIPS = 120;
   let totalHeight = 0;
@@ -665,6 +765,7 @@ function measureTableHeight(
           child,
           cellWidth,
           measurementProvider,
+          cache,
         );
       }
       contentHeight = Math.max(contentHeight, cellContentHeight + TABLE_ROW_PADDING_TWIPS);
@@ -896,6 +997,7 @@ function paginateSectionBlocks(
   layout: DocumentPageSnapshot["layout"],
   footnotes: FootnoteCollection | undefined,
   measurementProvider?: LayoutMeasurementProvider,
+  cache?: MeasurementCache,
 ): Omit<DocumentPageSnapshot, "pageIndex">[] {
   return paginateSectionBlocksWithSplits(
     section,
@@ -903,6 +1005,7 @@ function paginateSectionBlocks(
     layout,
     footnotes,
     measurementProvider,
+    cache,
   ).pages;
 }
 
@@ -912,6 +1015,7 @@ function paginateSectionBlocksWithSplits(
   layout: DocumentPageSnapshot["layout"],
   footnotes: FootnoteCollection | undefined,
   measurementProvider?: LayoutMeasurementProvider,
+  cache?: MeasurementCache,
 ): SectionPaginationResult {
   if (blocks.length === 0) {
     return {
@@ -939,6 +1043,10 @@ function paginateSectionBlocksWithSplits(
   let pageInSection = 0;
   let reservedNoteHeight = 0;
   const reservedNotes = new Set<string>();
+  // P6.c: per-table progress when a table is being split row-by-row
+  // across pages.  Map<blockId, nextRowIndexToPlace>.  Cleared once a
+  // table is fully placed.
+  const tableProgress = new Map<string, number>();
 
   const pushPage = (endOffset: number): void => {
     const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
@@ -967,13 +1075,13 @@ function paginateSectionBlocksWithSplits(
       const columnWidth =
         columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
         getUsableColumnWidth(layout);
-      const baseHeight = measureBlockHeight(block, columnWidth, measurementProvider);
+      const baseHeight = measureBlockHeight(block, columnWidth, measurementProvider, cache);
 
       // keepNext: this paragraph must stay with the next one on the same page
       const keepWithNextHeight =
         block.kind === "paragraph" && block.keepNext
           ? baseHeight +
-            measureBlockHeight(blocks[index + 1], columnWidth, measurementProvider)
+            measureBlockHeight(blocks[index + 1], columnWidth, measurementProvider, cache)
           : baseHeight;
 
       // keepLines: the entire paragraph must fit on one page.
@@ -990,6 +1098,88 @@ function paginateSectionBlocksWithSplits(
         continue;
       }
 
+      // P6.c: row-boundary split for tables that overflow the remaining
+      // page space (or that, on a fresh page, exceed one full page).
+      // Replaces the generic overflow path for table blocks.  Tables fall
+      // into one of four cases:
+      //
+      //   1. Remainder fits → place atomically, clear progress, break.
+      //   2. Remainder overflows AND splittable → place rows that fit,
+      //      push at the row-boundary offset, continue (next iteration
+      //      resumes from `splitRowIndex`).
+      //   3. Remainder overflows AND can't split AND has prior content →
+      //      push the whole remainder to the next page.
+      //   4. Remainder overflows AND can't split AND on fresh page →
+      //      degrade to atomic placement (visual overflow, but offset
+      //      ranges stay clean — same as pre-P6.c behavior).
+      if (block.kind === "table") {
+        const startRow = tableProgress.get(block.blockId) ?? 0;
+        const remainingForTable =
+          usableHeight - columnHeight - reservedNoteHeight;
+        const rowHeights = measureTableRowHeights({
+          block,
+          columnWidth,
+          measurementProvider,
+        });
+        const { cantSplitFlags, isHeaderFlags } = extractRowFlags(block);
+        const repeatedHeaderHeightTwips = computeRepeatedHeaderHeight(
+          rowHeights,
+          isHeaderFlags,
+        );
+        const headerReservation =
+          startRow > 0 ? repeatedHeaderHeightTwips : 0;
+        let remainderHeight = headerReservation;
+        for (let r = startRow; r < rowHeights.length; r += 1) {
+          remainderHeight += rowHeights[r] ?? 0;
+        }
+
+        // Helper: best-effort offset for the start of row K.  Falls back
+        // to the table block's `from` when the row has no inner block.
+        const rowOffset = (rowIndex: number): number => {
+          const row = block.rows[rowIndex];
+          const firstChild = row?.cells[0]?.content[0];
+          return firstChild?.from ?? block.from;
+        };
+
+        // Case 1: remainder fits — place and break.
+        if (remainderHeight <= remainingForTable) {
+          columnHeight += startRow > 0 ? remainderHeight : baseHeight;
+          if (startRow > 0) tableProgress.delete(block.blockId);
+          if (index === blocks.length - 1) pushPage(section.end);
+          break;
+        }
+
+        // Case 2: try a row-boundary split.
+        const decision = findTableRowSplit({
+          rowHeights,
+          cantSplitFlags,
+          isHeaderFlags,
+          remainingHeightTwips: remainingForTable,
+          repeatedHeaderHeightTwips,
+          startRow,
+        });
+        if (decision.rowsOnCurrentPage > 0) {
+          tableProgress.set(block.blockId, decision.splitRowIndex);
+          pushPage(rowOffset(decision.splitRowIndex));
+          continue;
+        }
+
+        // Case 3: can't split here.  If there's content above (or we're
+        // resuming), push everything from the resume point to the next
+        // page so the next iteration starts fresh.
+        if (columnHeight > 0 || startRow > 0) {
+          pushPage(startRow > 0 ? rowOffset(startRow) : block.from);
+          continue;
+        }
+
+        // Case 4: degraded atomic placement (table on a fresh page that
+        // it doesn't fit on, AND the first row alone exceeds page
+        // height).  Preserve pre-P6.c semantics so offsets stay clean.
+        columnHeight += baseHeight;
+        if (index === blocks.length - 1) pushPage(section.end);
+        break;
+      }
+
       // Overflow check — paragraph doesn't fit on current page
       if (projectedHeight > usableHeight && pageStart < block.from) {
         if (columnIndex < maxColumns - 1) {
@@ -1017,12 +1207,18 @@ function paginateSectionBlocksWithSplits(
           !block.keepNext
         ) {
           const availableHeight = usableHeight - columnHeight - reservedNoteHeight;
-          const totalLines = measureParagraphLineCount(
-            block,
-            formatting,
-            columnWidth,
-            measurementProvider,
-          );
+          const cachedLineCount = cache?.getLineCount(block, columnWidth);
+          const totalLines =
+            cachedLineCount ??
+            measureParagraphLineCount(
+              block,
+              formatting,
+              columnWidth,
+              measurementProvider,
+            );
+          if (cachedLineCount === undefined) {
+            cache?.setLineCount(block, columnWidth, totalLines);
+          }
           const availableLines =
             formatting.lineHeight > 0
               ? Math.max(0, Math.floor(availableHeight / formatting.lineHeight))

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

@@ -276,6 +276,32 @@ export type LayoutFacetEvent =
       kind: "zoom_changed";
       revision: number;
       zoom: RenderZoomSummary;
+    }
+  | {
+      /**
+       * P14.b — coalesced commit event.  Fires exactly once per
+       * `applyPatch`-driven layout build (full or incremental) AFTER
+       * the granular events.  Subscribers that only need to react
+       * to "the engine just finished a build" can listen here and
+       * skip the multi-event subscription pattern that triggered N
+       * React re-renders per applyPatch.
+       *
+       * Carries the union of: dirty-field families (TOC / PAGE /
+       * NUMPAGES etc.), page-count delta when the total changed, and
+       * the page range when the build was a bounded incremental
+       * relayout (absent for full rebuilds).  The granular events
+       * (`layout_recomputed`, `incremental_relayout`,
+       * `page_count_changed`, `page_field_dirtied`) still fire for
+       * backward-compat with consumers that care about specific
+       * kinds (e.g., `TwStatusBar` measurement-fidelity badge keys
+       * off `measurement_backend_ready`).
+       */
+      kind: "layout_committed";
+      revision: number;
+      reason?: LayoutFacetInvalidationReason;
+      dirtyFieldFamilies?: readonly string[];
+      pageCountDelta?: { previous: number; current: number };
+      pageRange?: { fromPageIndex: number; toPageIndex: number };
     };
 
 /**
@@ -338,6 +364,16 @@ export interface WordReviewEditorLayoutFacet {
     region: PublicPageRegion["kind"],
     options?: { columnIndex?: number },
   ): readonly PublicLineBox[];
+  /**
+   * P4 — every region present on the given page, in render order
+   * (header, body, columns…, footer, footnote-area).  Each entry
+   * carries the region kind, twip dimensions, and fragment count.
+   * Consumers iterate this to enumerate which regions exist before
+   * calling `getLineBoxesForRegion(pageIndex, kind)` to fetch
+   * their per-line breakdowns.  Returns an empty array when the
+   * pageIndex is out of range.
+   */
+  getStoryRegionsOnPage(pageIndex: number): readonly PublicPageRegion[];
   getFragmentsForPage(pageIndex: number): PublicBlockFragment[];
 
   // Page-format catalog --------------------------------------------------
@@ -414,6 +450,14 @@ export interface WordReviewEditorLayoutFacet {
   getMeasurementFidelity(): PublicMeasurementFidelity;
   whenMeasurementReady(): Promise<void>;
   swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+  /**
+   * Clear the active measurement provider's internal glyph / run-width
+   * cache AND the engine's cached page graph.  Call after
+   * `docxFontLoader.refresh(...)` so the canvas backend re-reads the
+   * newly-registered `FontFace` metrics and pagination re-runs with
+   * the fresh widths.  No-op on the inert facet.
+   */
+  invalidateMeasurementCache(): void;
 
   // Table render plan (P3e consumed by the render kernel, P4) ------------
   /**
@@ -497,6 +541,15 @@ export interface CreateLayoutFacetInput {
     | readonly import("../../api/public-types.ts").WorkflowMetadataMarkup[]
     | null
     | undefined;
+  /**
+   * R3 — optional suggestions snapshot accessor.  Used by
+   * `getAllScopeCardModels` to attach `SuggestionGroup` entries whose
+   * `issueId` matches the scope's issue.  Omit to skip group wiring.
+   */
+  getSuggestionsSnapshot?: () =>
+    | import("../../api/public-types.ts").SuggestionsSnapshot
+    | null
+    | undefined;
 }
 
 export function createLayoutFacet(
@@ -635,6 +688,7 @@ export function createLayoutFacet(
       return collectLineBoxesForRegion(
         node,
         region,
+        graph,
         options?.columnIndex,
       ).map((box) => toPublicLineBox(box));
     },
@@ -643,9 +697,39 @@ export function createLayoutFacet(
       const graph = currentGraph();
       const node = graph.pages[pageIndex];
       if (!node) return [];
-      return collectLineBoxesForRegion(node, region, options?.columnIndex).map(
-        (box) => toPublicLineBox(box),
-      );
+      return collectLineBoxesForRegion(
+        node,
+        region,
+        graph,
+        options?.columnIndex,
+      ).map((box) => toPublicLineBox(box));
+    },
+
+    getStoryRegionsOnPage(pageIndex) {
+      const graph = currentGraph();
+      const node = graph.pages[pageIndex];
+      if (!node) return [];
+      const result: PublicPageRegion[] = [];
+      // Render order: header → body → columns → footer → footnote-area.
+      if (node.regions.header) {
+        result.push(toPublicPageRegion(node.regions.header));
+      }
+      result.push(toPublicPageRegion(node.regions.body));
+      if (node.regions.columns) {
+        for (const column of node.regions.columns) {
+          result.push(toPublicPageRegion(column));
+        }
+      }
+      if (node.regions.footer) {
+        result.push(toPublicPageRegion(node.regions.footer));
+      }
+      const footnoteRegions = node.regions.footnotes;
+      if (footnoteRegions) {
+        for (const footnote of footnoteRegions) {
+          result.push(toPublicPageRegion(footnote));
+        }
+      }
+      return result;
     },
 
     getPageFormatCatalog() {
@@ -744,11 +828,18 @@ export function createLayoutFacet(
       const kernel = input.renderKernel?.();
       const anchorIndex = kernel?.getRenderFrame?.()?.anchorIndex ?? null;
       const metadata = input.getWorkflowMarkupMetadata?.();
+      const suggestions = input.getSuggestionsSnapshot?.() ?? null;
+      // The workflow-markup entries carry BOTH issue and review-action
+      // metadata.  The projector filters to REVIEW_ACTION_METADATA_ID
+      // internally, so we can just pass the whole list.
       return attachScopeCardModel({
         segments,
         scopes: railInput?.scopes ?? [],
         metadata: metadata ?? undefined,
         anchorIndex,
+        suggestions,
+        reviewActionMetadata: metadata ?? undefined,
+        candidates: railInput?.candidates ?? undefined,
       });
     },
 
@@ -816,6 +907,10 @@ export function createLayoutFacet(
       engine.swapMeasurementProvider(provider);
     },
 
+    invalidateMeasurementCache() {
+      engine.invalidateMeasurementCache();
+    },
+
     getTableRenderPlan(blockId, pageIndex) {
       const graph = currentGraph();
       const fragment = graph.fragments.find((f) => f.blockId === blockId);
@@ -1077,6 +1172,17 @@ function toFacetEvent(
         ...(event.reason ? { reason: event.reason } : {}),
       };
     }
+    case "layout_committed":
+      return {
+        kind: "layout_committed",
+        revision: event.revision,
+        ...(event.reason ? { reason: event.reason } : {}),
+        ...(event.dirtyFieldFamilies && event.dirtyFieldFamilies.length > 0
+          ? { dirtyFieldFamilies: event.dirtyFieldFamilies }
+          : {}),
+        ...(event.pageCountDelta ? { pageCountDelta: event.pageCountDelta } : {}),
+        ...(event.pageRange ? { pageRange: event.pageRange } : {}),
+      };
     default:
       return null;
   }
@@ -1173,24 +1279,90 @@ function findPageForOffsetAndStory(
 /**
  * Select line boxes that belong to a given region on a page.
  *
- * Today the engine populates body line boxes only; header/footer/column/
- * footnote-area regions produce empty arrays until the render kernel lands
- * (Phase R1).  The region filter is now exact: `body` returns only body
- * line boxes, everything else returns empty.  Consumers should prefer
- * `getLineBoxes(pageIndex, { region: "body" })` — the other kinds are
- * scaffolded so UI can start reading through the facet without special-
- * casing region availability.
+ * `body` returns the engine's per-page measured line boxes (one per
+ * line of paginated body content).
+ *
+ * `header` / `footer` / `footnote-area` / `column` (P4): synthesizes
+ * one line box per fragment in the region.  Header/footer fragments
+ * aren't paginated themselves — the engine reserves space for the
+ * entire header story per page — so per-line measurements are not
+ * available.  The synthesized line box uses each fragment's
+ * `heightTwips` as the line height with cumulative `baselineTwips`
+ * from the region origin.  This gives consumers (page stack, P8
+ * region rendering) a uniform iteration shape across regions.
+ *
+ * `endnote-area` always returns empty: endnote bodies are emitted at
+ * the document end as a separate region whose layout sits outside
+ * the per-page accounting.
  */
 function collectLineBoxesForRegion(
   node: RuntimePageNode,
   region: PublicPageRegion["kind"],
-  _columnIndex: number | undefined,
+  graph: RuntimePageGraph,
+  columnIndex: number | undefined,
 ): readonly RuntimeLineBoxAlias[] {
-  void _columnIndex;
   if (region === "body") {
     return node.lineBoxes;
   }
-  return EMPTY_LINE_BOXES;
+  // P4: synthesize line boxes from the region's fragments.
+  const regionEntry = resolveRegionEntry(node, region, columnIndex);
+  if (!regionEntry || regionEntry.fragmentIds.length === 0) {
+    return EMPTY_LINE_BOXES;
+  }
+  const fragmentsById = new Map(
+    graph.fragments.map((f) => [f.fragmentId, f] as const),
+  );
+  const result: RuntimeLineBoxAlias[] = [];
+  let cursorTwips = 0;
+  let lineIndex = 0;
+  for (const fragmentId of regionEntry.fragmentIds) {
+    const fragment = fragmentsById.get(fragmentId);
+    if (!fragment) continue;
+    const heightTwips = Math.max(1, fragment.heightTwips);
+    result.push({
+      fragmentId,
+      lineIndex: lineIndex++,
+      baselineTwips: cursorTwips + heightTwips,
+      heightTwips,
+      widthTwips: regionEntry.widthTwips,
+    });
+    cursorTwips += heightTwips;
+  }
+  return result;
+}
+
+function resolveRegionEntry(
+  node: RuntimePageNode,
+  region: PublicPageRegion["kind"],
+  columnIndex: number | undefined,
+): RuntimePageRegion | undefined {
+  switch (region) {
+    case "header":
+      return node.regions.header;
+    case "footer":
+      return node.regions.footer;
+    case "column": {
+      const columns = node.regions.columns ?? [];
+      if (columns.length === 0) return undefined;
+      const idx = columnIndex ?? 0;
+      return columns[idx];
+    }
+    case "footnote-area": {
+      // Footnote area sits at the bottom of the body region per
+      // OOXML.  `RuntimePageRegions.footnotes` is a stable seam
+      // declared by P4; the page-graph builder populates entries
+      // when P8 lands.  Returns the first footnote region (page
+      // layouts allocate one block of footnotes per page; multi-
+      // block layouts come later).
+      const footnoteRegionList = node.regions.footnotes;
+      if (footnoteRegionList && footnoteRegionList.length > 0) {
+        return footnoteRegionList[0];
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
 }
 
 // Use a shared alias so the region helper doesn't import the runtime