@beyondwork/docx-react-component 1.0.41 → 1.0.43

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

@@ -62,8 +62,12 @@ import {
   type ScopeRailSegment,
 } from "../workflow-rail-segments.ts";
 import { createEditorSurfaceSnapshot } from "../surface-projection.ts";
+import { storyTargetKey } from "../story-targeting.ts";
 import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
-import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+} from "../../core/state/editor-state.ts";
 import { resolveTableStyleResolution } from "../table-style-resolver.ts";
 import { buildTableRenderPlan } from "./table-render-plan.ts";
 import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
@@ -124,6 +128,13 @@ export interface PublicPageRegions {
   header?: PublicPageRegion;
   footer?: PublicPageRegion;
   columns?: readonly PublicPageRegion[];
+  /**
+   * P8.3 — Footnote regions reserved at the bottom of the page (above the
+   * footer band). Mirrors `RuntimePageRegions.footnotes`. Present only
+   * when at least one allocation on this page produced a fragment — see
+   * `noteAllocations` for per-note metadata. Additive / back-compat safe.
+   */
+  footnotes?: readonly PublicPageRegion[];
 }
 
 export interface PublicPageRegion {
@@ -134,6 +145,15 @@ export interface PublicPageRegion {
   fragmentCount: number;
 }
 
+/**
+ * P8 — Region kind discriminator used by `PublicRegionBlock` and the
+ * `getStoryBlocksForRegion` API.  Mirrors `PublicPageRegion["kind"]` plus
+ * `"endnote-area"`, which is only ever surfaced via
+ * `getDocumentEndnoteBlocks` (endnotes have document-end placement and
+ * never sit on a body page).
+ */
+export type PublicRegionKind = PublicPageRegion["kind"] | "endnote-area";
+
 export interface PublicBlockFragment {
   fragmentId: string;
   blockId: string;
@@ -146,6 +166,29 @@ export interface PublicBlockFragment {
   orderInRegion: number;
 }
 
+/**
+ * P8 — One block snapshot rendered into a region of a page.  Returned by
+ * `WordReviewEditorLayoutFacet.getStoryBlocksForRegion` and
+ * `getDocumentEndnoteBlocks`.
+ *
+ * The `blockSnapshot` field is the same `SurfaceBlockSnapshot` consumed by
+ * the body block renderer (`tw-page-block-view`), so region renderers reuse
+ * body typography verbatim.  For body fragments `runtimeFromOffset`/`To`
+ * mirror the underlying `RuntimeBlockFragment.from`/`to`.  For header /
+ * footer / footnote-area blocks the offsets are local to the host story
+ * (header story, footer story, or note body).
+ */
+export interface PublicRegionBlock {
+  blockId: string;
+  fragmentId: string;
+  pageIndex: number;
+  regionKind: PublicRegionKind;
+  runtimeFromOffset: number;
+  runtimeToOffset: number;
+  heightTwips: number;
+  blockSnapshot: SurfaceBlockSnapshot;
+}
+
 export interface PublicLineBox {
   fragmentId: string;
   lineIndex: number;
@@ -276,6 +319,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,8 +407,41 @@ 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[];
 
+  /**
+   * P8 — Returns per-region block snapshots for a page.  Body resolves the
+   * page's body fragments to their `SurfaceBlockSnapshot`s; header / footer
+   * resolve via the page's active story target + `subParts.headers/footers`
+   * lookup; footnote-area resolves per-page `noteAllocations` against
+   * `subParts.footnoteCollection.footnotes`.  Endnote-area is always empty
+   * per-page — document-end placement is handled by
+   * `getDocumentEndnoteBlocks`.  Column falls through to body (multi-column
+   * splitting is a P10 follow-up).  Cached per revision; busts on
+   * `graph.revision` change.
+   */
+  getStoryBlocksForRegion(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    options?: { columnIndex?: number },
+  ): readonly PublicRegionBlock[];
+
+  /**
+   * P8 — Returns endnote bodies in document order for document-end
+   * placement (per OOXML default `w:endnotePr/w:pos="docEnd"`).
+   */
+  getDocumentEndnoteBlocks(): readonly PublicRegionBlock[];
+
   // Page-format catalog --------------------------------------------------
   getPageFormatCatalog(): readonly PageFormatDefinition[];
   getActivePageFormat(sectionIndex: number): ActivePageFormat | null;
@@ -414,6 +516,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) ------------
   /**
@@ -465,6 +575,13 @@ export interface WordReviewEditorLayoutFacet {
 export interface CreateLayoutFacetInput {
   engine: LayoutEngineInstance;
   getQueryInput: () => LayoutEngineQueryInput;
+  /**
+   * P8 — Canonical document accessor used by `getStoryBlocksForRegion` /
+   * `getDocumentEndnoteBlocks` to resolve header / footer / footnote /
+   * endnote stories in `subParts`.  When omitted the facet falls back to
+   * the document available on the engine query input.
+   */
+  canonicalDocument?: () => CanonicalDocumentEnvelope;
   /**
    * Optional render-kernel accessor.  When supplied, the facet exposes
    * `getRenderFrame` + `getRenderZoom` that delegate to the kernel.
@@ -497,6 +614,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(
@@ -540,6 +666,151 @@ export function createLayoutFacet(
   // Keep the handle alive; the facet instance lives as long as the runtime.
   void unsubscribeEngine;
 
+  // P8 — per-revision cache for getStoryBlocksForRegion.  Identity is
+  // preserved within a single graph revision so consumers can `===`-compare
+  // results across band renders, and the cache flushes whenever the engine
+  // produces a fresh page graph.
+  let regionBlocksCache: {
+    revision: number;
+    byKey: Map<string, readonly PublicRegionBlock[]>;
+  } = { revision: -1, byKey: new Map() };
+  // P8.2.1 — secondary cache keyed by header/footer story-target identity.
+  // A 38-page doc with one default header projects the story once instead of
+  // 38 times; per-page `PublicRegionBlock[]`s still differ (each carries the
+  // page's `pageIndex`), but the underlying `SurfaceBlockSnapshot[]` and
+  // every `blockSnapshot` reference are shared.  Busts together with
+  // `regionBlocksCache` on `graph.revision` change.
+  let storyProjectionCache: {
+    revision: number;
+    byKey: Map<string, readonly SurfaceBlockSnapshot[]>;
+  } = { revision: -1, byKey: new Map() };
+  // P8 — per-revision cache for getDocumentEndnoteBlocks (single key).
+  let endnoteBlocksCache: {
+    revision: number;
+    blocks: readonly PublicRegionBlock[] | null;
+  } = { revision: -1, blocks: null };
+
+  function resolveCanonicalDocument(): CanonicalDocumentEnvelope {
+    if (input.canonicalDocument) {
+      return input.canonicalDocument();
+    }
+    return getQueryInput().document;
+  }
+
+  /**
+   * Build the body story's `SurfaceBlockSnapshot[]` so body fragment
+   * `blockId`s can be resolved.  Cached against the canonical document
+   * identity to avoid re-walking the body on every region read.
+   */
+  let cachedBodySurface: {
+    document: CanonicalDocumentEnvelope;
+    blocks: readonly SurfaceBlockSnapshot[];
+  } | null = null;
+  function bodySurfaceBlocks(): readonly SurfaceBlockSnapshot[] {
+    const document = resolveCanonicalDocument();
+    if (cachedBodySurface && cachedBodySurface.document === document) {
+      return cachedBodySurface.blocks;
+    }
+    const surface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      MAIN_STORY_TARGET,
+    );
+    cachedBodySurface = { document, blocks: surface.blocks };
+    return surface.blocks;
+  }
+
+  function findBodyBlockById(
+    blockId: string,
+  ): SurfaceBlockSnapshot | undefined {
+    return bodySurfaceBlocks().find((b) => b.blockId === blockId);
+  }
+
+  function getRegionBlocksCached(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    columnIndex: number | undefined,
+  ): readonly PublicRegionBlock[] {
+    const graph = currentGraph();
+    if (regionBlocksCache.revision !== graph.revision) {
+      regionBlocksCache = { revision: graph.revision, byKey: new Map() };
+      // P8.2.1 — bust the secondary story-projection cache in lock-step so
+      // shared `SurfaceBlockSnapshot`s never outlive their graph revision.
+      storyProjectionCache = { revision: graph.revision, byKey: new Map() };
+      // Body surface depends on the canonical document; the document
+      // identity check inside `bodySurfaceBlocks` keeps it warm across
+      // pure-layout invalidations (zoom, font, etc.).
+    }
+    const key = `${pageIndex}:${region}:${columnIndex ?? "_"}`;
+    const cached = regionBlocksCache.byKey.get(key);
+    if (cached) return cached;
+    const fresh = computeRegionBlocks(pageIndex, region, columnIndex, graph);
+    regionBlocksCache.byKey.set(key, fresh);
+    return fresh;
+  }
+
+  /**
+   * P8.2.1 — shared projection for a header/footer story.  Returns the same
+   * `SurfaceBlockSnapshot[]` array identity for repeated calls at the same
+   * revision so per-page `PublicRegionBlock[]`s can share every
+   * `blockSnapshot` reference.
+   */
+  function getStoryProjectionCached(
+    storyTarget: EditorStoryTarget,
+    document: CanonicalDocumentEnvelope,
+  ): readonly SurfaceBlockSnapshot[] {
+    const key = storyTargetKey(storyTarget);
+    const cached = storyProjectionCache.byKey.get(key);
+    if (cached) return cached;
+    const surface = createEditorSurfaceSnapshot(
+      document,
+      createSelectionSnapshot(0, 0),
+      storyTarget,
+    );
+    const fresh = surface.blocks;
+    storyProjectionCache.byKey.set(key, fresh);
+    return fresh;
+  }
+
+  function computeRegionBlocks(
+    pageIndex: number,
+    region: PublicPageRegion["kind"],
+    columnIndex: number | undefined,
+    graph: RuntimePageGraph,
+  ): readonly PublicRegionBlock[] {
+    const node = graph.pages[pageIndex];
+    if (!node) return Object.freeze([]);
+    const document = resolveCanonicalDocument();
+    if (region === "body") {
+      return resolveBodyRegionBlocks(node, graph, findBodyBlockById);
+    }
+    if (region === "header" || region === "footer") {
+      const story =
+        region === "header" ? node.stories.header : node.stories.footer;
+      if (!story) return Object.freeze([]);
+      // P8.2.1 — share the projected `SurfaceBlockSnapshot[]` across every
+      // page that renders the same story target.
+      const projectedBlocks = getStoryProjectionCached(story, document);
+      return resolveHeaderFooterRegionBlocks(
+        node.pageIndex,
+        region,
+        story,
+        projectedBlocks,
+      );
+    }
+    if (region === "footnote-area") {
+      return resolveFootnoteAreaRegionBlocks(node, document);
+    }
+    if (region === "column") {
+      // Multi-column body splitting is a P10 follow-up.  For now reuse
+      // the body fragments for the indexed column.
+      void columnIndex;
+      return resolveBodyRegionBlocks(node, graph, findBodyBlockById);
+    }
+    // endnote-area: empty per-page; document-end via getDocumentEndnoteBlocks.
+    return Object.freeze([]);
+  }
+
   return {
     getPageCount() {
       return currentGraph().pages.length;
@@ -635,6 +906,7 @@ export function createLayoutFacet(
       return collectLineBoxesForRegion(
         node,
         region,
+        graph,
         options?.columnIndex,
       ).map((box) => toPublicLineBox(box));
     },
@@ -643,9 +915,102 @@ 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;
+    },
+
+    getStoryBlocksForRegion(pageIndex, region, options) {
+      return getRegionBlocksCached(pageIndex, region, options?.columnIndex);
+    },
+
+    getDocumentEndnoteBlocks() {
+      const graph = currentGraph();
+      if (endnoteBlocksCache.revision === graph.revision && endnoteBlocksCache.blocks) {
+        return endnoteBlocksCache.blocks;
+      }
+      const document = resolveCanonicalDocument();
+      const collection = document.subParts?.footnoteCollection;
+      const blocks: PublicRegionBlock[] = [];
+      if (collection) {
+        // P8.2.1 — batch every endnote body into one
+        // `createEditorSurfaceSnapshot` call.  Previously we called the
+        // projector once per block (50 endnotes × 1 block → 50 full
+        // projections); now we project the flat concatenation once and
+        // slice the result back into per-note groups using the original
+        // block counts.  `runtimeFromOffset` / `runtimeToOffset` inherit
+        // the projection's cumulative cursor (a stable "all-endnotes"
+        // meta-story offset); fragment ids still scope per-note so
+        // consumers can tell which endnote a block belongs to.
+        const groups: Array<{ noteId: string; count: number }> = [];
+        const flat: import("../../model/canonical-document.ts").BlockNode[] = [];
+        for (const noteId of Object.keys(collection.endnotes)) {
+          const note = collection.endnotes[noteId];
+          if (!note || note.blocks.length === 0) continue;
+          groups.push({ noteId, count: note.blocks.length });
+          for (const block of note.blocks) flat.push(block);
+        }
+        if (flat.length > 0) {
+          const surface = createEditorSurfaceSnapshot(
+            {
+              ...document,
+              content: { type: "doc", children: flat },
+            } as CanonicalDocumentEnvelope,
+            createSelectionSnapshot(0, 0),
+          );
+          let cursor = 0;
+          for (const group of groups) {
+            for (let i = 0; i < group.count; i += 1) {
+              const blockSnapshot = surface.blocks[cursor + i];
+              if (!blockSnapshot) continue;
+              blocks.push({
+                blockId: blockSnapshot.blockId,
+                fragmentId: `endnote-${group.noteId}-${i}`,
+                pageIndex: -1,
+                regionKind: "endnote-area",
+                runtimeFromOffset: blockSnapshot.from,
+                runtimeToOffset: blockSnapshot.to,
+                heightTwips: 0,
+                blockSnapshot,
+              });
+            }
+            cursor += group.count;
+          }
+        }
+      }
+      const frozen = Object.freeze(blocks);
+      endnoteBlocksCache = { revision: graph.revision, blocks: frozen };
+      return frozen;
     },
 
     getPageFormatCatalog() {
@@ -744,11 +1109,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 +1188,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);
@@ -910,6 +1286,9 @@ function toPublicPageRegions(regions: RuntimePageRegions): PublicPageRegions {
     ...(regions.header ? { header: toPublicPageRegion(regions.header) } : {}),
     ...(regions.footer ? { footer: toPublicPageRegion(regions.footer) } : {}),
     ...(regions.columns ? { columns: regions.columns.map(toPublicPageRegion) } : {}),
+    ...(regions.footnotes && regions.footnotes.length > 0
+      ? { footnotes: regions.footnotes.map(toPublicPageRegion) }
+      : {}),
   };
 }
 
@@ -1077,6 +1456,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 +1563,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
@@ -1476,3 +1932,118 @@ function findCanonicalTableByBlockId(
   }
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// P8 — region-block resolvers
+// ---------------------------------------------------------------------------
+
+function resolveBodyRegionBlocks(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+  findBodyBlockById: (blockId: string) => SurfaceBlockSnapshot | undefined,
+): readonly PublicRegionBlock[] {
+  const fragmentsById = new Map<string, RuntimeBlockFragment>();
+  for (const fragment of graph.fragments) {
+    fragmentsById.set(fragment.fragmentId, fragment);
+  }
+  const blocks: PublicRegionBlock[] = [];
+  for (const fragmentId of node.regions.body.fragmentIds) {
+    const fragment = fragmentsById.get(fragmentId);
+    if (!fragment) continue;
+    const blockSnapshot = findBodyBlockById(fragment.blockId);
+    if (!blockSnapshot) continue;
+    blocks.push({
+      blockId: fragment.blockId,
+      fragmentId,
+      pageIndex: node.pageIndex,
+      regionKind: "body",
+      runtimeFromOffset: fragment.from,
+      runtimeToOffset: fragment.to,
+      heightTwips: fragment.heightTwips,
+      blockSnapshot,
+    });
+  }
+  return Object.freeze(blocks);
+}
+
+function resolveHeaderFooterRegionBlocks(
+  pageIndex: number,
+  regionKind: "header" | "footer",
+  storyTarget: EditorStoryTarget,
+  projectedBlocks: readonly SurfaceBlockSnapshot[],
+): readonly PublicRegionBlock[] {
+  if (storyTarget.kind !== regionKind) return Object.freeze([]);
+  if (projectedBlocks.length === 0) return Object.freeze([]);
+  const fragmentBase = `story-${storyTarget.kind}-${storyTarget.relationshipId}-${storyTarget.variant}-${storyTarget.sectionIndex ?? "_"}`;
+  return Object.freeze(
+    projectedBlocks.map((blockSnapshot, index): PublicRegionBlock => ({
+      blockId: blockSnapshot.blockId,
+      fragmentId: `${fragmentBase}-${index}`,
+      pageIndex,
+      regionKind,
+      runtimeFromOffset: blockSnapshot.from,
+      runtimeToOffset: blockSnapshot.to,
+      // Header/footer fragments aren't measured per-block — consumers read
+      // the region's `heightTwips` from `getStoryRegionsOnPage`.
+      heightTwips: 0,
+      blockSnapshot,
+    })),
+  );
+}
+
+function resolveFootnoteAreaRegionBlocks(
+  node: RuntimePageNode,
+  document: CanonicalDocumentEnvelope,
+): readonly PublicRegionBlock[] {
+  const collection = document.subParts?.footnoteCollection;
+  if (!collection) return Object.freeze([]);
+  // P8.2.1 — batch every allocation's body into one
+  // `createEditorSurfaceSnapshot` call and slice the result back into
+  // per-allocation groups.  Amplification per-page is small (a handful of
+  // footnotes), but this mirrors the endnote batching so both paths take
+  // the same shape.  The existence guard on `note` is sufficient — the
+  // previous `void note;` marker is gone.
+  const groups: Array<{
+    allocation: RuntimeNoteAllocation;
+    count: number;
+  }> = [];
+  const flat: import("../../model/canonical-document.ts").BlockNode[] = [];
+  for (const allocation of node.noteAllocations) {
+    if (allocation.noteKind !== "footnote") continue;
+    const note = collection.footnotes[allocation.noteId];
+    if (!note || note.blocks.length === 0) continue;
+    groups.push({ allocation, count: note.blocks.length });
+    for (const block of note.blocks) flat.push(block);
+  }
+  if (flat.length === 0) return Object.freeze([]);
+  const surface = createEditorSurfaceSnapshot(
+    {
+      ...document,
+      content: { type: "doc", children: flat },
+    } as CanonicalDocumentEnvelope,
+    createSelectionSnapshot(0, 0),
+  );
+  const blocks: PublicRegionBlock[] = [];
+  let cursor = 0;
+  for (const group of groups) {
+    const fragmentBase = group.allocation.fragmentId
+      ?? `note-${node.pageIndex}-${group.allocation.noteId}`;
+    for (let i = 0; i < group.count; i += 1) {
+      const blockSnapshot = surface.blocks[cursor + i];
+      if (!blockSnapshot) continue;
+      blocks.push({
+        blockId: blockSnapshot.blockId,
+        fragmentId: `${fragmentBase}-${i}`,
+        pageIndex: node.pageIndex,
+        regionKind: "footnote-area",
+        runtimeFromOffset: blockSnapshot.from,
+        runtimeToOffset: blockSnapshot.to,
+        heightTwips: group.allocation.reservedHeightTwips,
+        blockSnapshot,
+      });
+    }
+    cursor += group.count;
+  }
+  return Object.freeze(blocks);
+}
+