@beyondwork/docx-react-component 1.0.41 → 1.0.43

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

@@ -41,6 +41,10 @@ import type {
   FootnoteCollection,
 } from "../../model/canonical-document.ts";
 import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  RuntimeNoteAllocation,
+  RuntimeBlockFragment,
+} from "./page-graph.ts";
 import {
   buildPageLayoutSnapshot,
   buildResolvedSections,
@@ -63,6 +67,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
@@ -132,6 +142,19 @@ export interface BlockSplits {
 export interface PageStackResultWithSplits {
   pages: DocumentPageSnapshot[];
   splits: BlockSplits;
+  /**
+   * P8.1b — per-page note allocations emitted by the engine.
+   * Keyed by zero-based global page index.
+   * Absent entries mean the page has no footnotes.
+   * Endnote allocations are deferred to P8 Task 7.
+   */
+  noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
+  /**
+   * P8.1b — per-page note body fragments emitted by the engine.
+   * Each fragment has `regionKind: "footnote-area"`.
+   * Parallel to `noteAllocationsByPageIndex`.
+   */
+  noteFragmentsByPageIndex?: ReadonlyMap<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
 }
 
 // ---------------------------------------------------------------------------
@@ -176,7 +199,19 @@ export function buildPageStackWithSplits(
 ): PageStackResultWithSplits {
   const pages: DocumentPageSnapshot[] = [];
   const splitsByBlock = new Map<string, ParagraphLineSlice[]>();
+  // P8.1b — aggregate note allocations and fragments across all sections,
+  // keyed by global page index.
+  const globalNoteAllocationsByPageIndex = new Map<number, RuntimeNoteAllocation[]>();
+  const globalNoteFragmentsByPageIndex = new Map<
+    number,
+    Array<Omit<RuntimeBlockFragment, "pageId">>
+  >();
   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 +269,7 @@ export function buildPageStackWithSplits(
       layout,
       document.subParts?.footnoteCollection,
       measurementProvider,
+      cache,
     );
     const paginated = paginatedResult.pages;
 
@@ -293,6 +329,21 @@ export function buildPageStackWithSplits(
       }
       if (existing.length > 0) splitsByBlock.set(blockId, existing);
     }
+
+    // P8.1b — resolve per-section note allocations + fragments to global
+    // page index and merge into the global maps.
+    for (const [pageInSec, sectionAllocs] of paginatedResult.noteAllocationsByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      const existing = globalNoteAllocationsByPageIndex.get(globalPageIdx) ?? [];
+      globalNoteAllocationsByPageIndex.set(globalPageIdx, [...existing, ...sectionAllocs]);
+    }
+    for (const [pageInSec, sectionFrags] of paginatedResult.noteFragmentsByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      const existing = globalNoteFragmentsByPageIndex.get(globalPageIdx) ?? [];
+      globalNoteFragmentsByPageIndex.set(globalPageIdx, [...existing, ...sectionFrags]);
+    }
   }
 
   // Guarantee at least one page
@@ -316,6 +367,12 @@ export function buildPageStackWithSplits(
   return {
     pages,
     splits: { byBlockId: splitsByBlock, tablesByBlockId: tableSplitsByBlock },
+    noteAllocationsByPageIndex: globalNoteAllocationsByPageIndex.size > 0
+      ? globalNoteAllocationsByPageIndex
+      : undefined,
+    noteFragmentsByPageIndex: globalNoteFragmentsByPageIndex.size > 0
+      ? globalNoteFragmentsByPageIndex
+      : undefined,
   };
 }
 
@@ -560,6 +617,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 +677,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 +765,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 +810,7 @@ function measureTableHeight(
           child,
           cellWidth,
           measurementProvider,
+          cache,
         );
       }
       contentHeight = Math.max(contentHeight, cellContentHeight + TABLE_ROW_PADDING_TWIPS);
@@ -883,6 +1029,10 @@ interface SectionLocalSlice {
 interface SectionPaginationResult {
   pages: Omit<DocumentPageSnapshot, "pageIndex">[];
   splits: { byBlockId: Map<string, SectionLocalSlice[]> };
+  /** P8.1b — per-page note allocations keyed by pageInSection index. */
+  noteAllocationsByPageInSection: Map<number, RuntimeNoteAllocation[]>;
+  /** P8.1b — per-page note body fragments keyed by pageInSection index. */
+  noteFragmentsByPageInSection: Map<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
 }
 
 /**
@@ -896,6 +1046,7 @@ function paginateSectionBlocks(
   layout: DocumentPageSnapshot["layout"],
   footnotes: FootnoteCollection | undefined,
   measurementProvider?: LayoutMeasurementProvider,
+  cache?: MeasurementCache,
 ): Omit<DocumentPageSnapshot, "pageIndex">[] {
   return paginateSectionBlocksWithSplits(
     section,
@@ -903,15 +1054,17 @@ function paginateSectionBlocks(
     layout,
     footnotes,
     measurementProvider,
+    cache,
   ).pages;
 }
 
-function paginateSectionBlocksWithSplits(
+export function paginateSectionBlocksWithSplits(
   section: ResolvedDocumentSection,
   blocks: readonly SurfaceBlockSnapshot[],
   layout: DocumentPageSnapshot["layout"],
   footnotes: FootnoteCollection | undefined,
   measurementProvider?: LayoutMeasurementProvider,
+  cache?: MeasurementCache,
 ): SectionPaginationResult {
   if (blocks.length === 0) {
     return {
@@ -925,6 +1078,8 @@ function paginateSectionBlocksWithSplits(
         },
       ],
       splits: { byBlockId: new Map() }, // section-local; global map includes tablesByBlockId via collectTableRowSlices
+      noteAllocationsByPageInSection: new Map(),
+      noteFragmentsByPageInSection: new Map(),
     };
   }
 
@@ -939,15 +1094,109 @@ 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>();
+
+  // P8.1b — per-page note tracking.
+  // `pendingNoteKeys` parallels `reservedNotes` but is only snapshotted on
+  // page-push (finalization), NOT on column break.
+  // `pendingNoteBlockFroms` records the referencing block's `from` offset
+  // for each note key, enabling hit-test via `RuntimeBlockFragment.from`.
+  const noteAllocationsByPageInSection = new Map<number, RuntimeNoteAllocation[]>();
+  const noteFragmentsByPageInSection = new Map<
+    number,
+    Array<Omit<RuntimeBlockFragment, "pageId">>
+  >();
+  const pendingNoteKeys = new Set<string>();
+  const pendingNoteBlockFroms = new Map<string, { blockFrom: number; blockTo: number }>();
+  // Track the columnWidth at the time each note was accumulated so the
+  // measurement is reproducible at page-close time.
+  const pendingNoteColumnWidths = new Map<string, number>();
+
+  /**
+   * Snapshot the pending note state into `noteAllocationsByPageInSection` and
+   * `noteFragmentsByPageInSection` for the page that is about to close.
+   * Must be called BEFORE clearing `pendingNoteKeys`.
+   */
+  const snapshotNoteAllocations = (closingPageInSection: number, columnWidth: number): void => {
+    if (pendingNoteKeys.size === 0 || !footnotes) return;
+
+    const allocations: RuntimeNoteAllocation[] = [];
+    const fragments: Array<Omit<RuntimeBlockFragment, "pageId">> = [];
+    let orderInRegion = 0;
+
+    for (const noteKey of pendingNoteKeys) {
+      const colonIdx = noteKey.indexOf(":");
+      if (colonIdx === -1) continue;
+      const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+      const noteId = noteKey.slice(colonIdx + 1);
+
+      // P8.1b: endnote allocations are deferred to P8 Task 7 (endnote area
+      // component).  The existing reservedNoteHeight math still reserves space
+      // for endnotes, but we do not emit RuntimeNoteAllocation for them here.
+      // See P8 plan, Task 7.
+      if (noteKind === "endnote") continue;
+
+      const effectiveColumnWidth =
+        pendingNoteColumnWidths.get(noteKey) ?? columnWidth;
+      const { heightTwips } = measureNoteBody(
+        noteKind,
+        noteId,
+        footnotes,
+        effectiveColumnWidth,
+      );
+
+      const fragmentId = `note-${closingPageInSection}-${noteKind}-${noteId}`;
+      const refRange = pendingNoteBlockFroms.get(noteKey) ?? {
+        blockFrom: pageStart,
+        blockTo: pageStart + 1,
+      };
+
+      const allocation: RuntimeNoteAllocation = {
+        noteKind,
+        noteId,
+        reservedHeightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+        fragmentId,
+      };
+
+      const fragment: Omit<RuntimeBlockFragment, "pageId"> = {
+        fragmentId,
+        blockId: `note-body-${noteKind}-${noteId}`,
+        orderInRegion,
+        regionKind: "footnote-area",
+        from: refRange.blockFrom,
+        to: refRange.blockTo,
+        heightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+        kind: "whole",
+      };
+
+      allocations.push(allocation);
+      fragments.push(fragment);
+      orderInRegion += 1;
+    }
+
+    if (allocations.length > 0) {
+      noteAllocationsByPageInSection.set(closingPageInSection, allocations);
+      noteFragmentsByPageInSection.set(closingPageInSection, fragments);
+    }
+  };
 
   const pushPage = (endOffset: number): void => {
     const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
     if (boundedEnd === pageStart && pages.length > 0) {
       return;
     }
+    const closingPageInSection = pageInSection;
+    const columnWidth =
+      columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
+      getUsableColumnWidth(layout);
+    // Snapshot note allocations for the page being closed BEFORE clearing state.
+    snapshotNoteAllocations(closingPageInSection, columnWidth);
     pages.push({
       sectionIndex: section.index,
-      pageInSection,
+      pageInSection: closingPageInSection,
       startOffset: pageStart,
       endOffset: boundedEnd,
       layout,
@@ -958,6 +1207,10 @@ function paginateSectionBlocksWithSplits(
     columnIndex = 0;
     reservedNoteHeight = 0;
     reservedNotes.clear();
+    // P8.1b: also clear pending note tracking on page finalization.
+    pendingNoteKeys.clear();
+    pendingNoteBlockFroms.clear();
+    pendingNoteColumnWidths.clear();
   };
 
   for (let index = 0; index < blocks.length; index += 1) {
@@ -967,13 +1220,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,13 +1243,100 @@ 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) {
+          // Advance to next column without a page break — do NOT snapshot.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
           continue;
         }
 
@@ -1017,12 +1357,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))
@@ -1068,10 +1414,15 @@ function paginateSectionBlocksWithSplits(
       // span the full page if it's truly larger than a page).
       if (keepLinesActive && columnHeight > 0 && baseHeight > usableHeight - columnHeight && pageStart < block.from) {
         if (columnIndex < maxColumns - 1) {
+          // Column advance without page break — do NOT snapshot.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
           continue;
         }
         pushPage(block.from);
@@ -1086,14 +1437,32 @@ function paginateSectionBlocksWithSplits(
       );
       columnHeight += baseHeight;
       reservedNoteHeight += effectiveNoteHeight;
-      currentPageNoteIds(block).forEach((noteKey) => reservedNotes.add(noteKey));
+      currentPageNoteIds(block).forEach((noteKey) => {
+        reservedNotes.add(noteKey);
+        // P8.1b: also track the referencing block range for hit-test.
+        // Only record the first reference (earliest block.from) per noteKey
+        // so the fragment's from/to points to the paragraph that introduced it.
+        if (!pendingNoteKeys.has(noteKey)) {
+          pendingNoteKeys.add(noteKey);
+          pendingNoteBlockFroms.set(noteKey, { blockFrom: block.from, blockTo: block.to });
+          pendingNoteColumnWidths.set(noteKey, columnWidth);
+        }
+      });
 
       if (hasColumnBreak(block)) {
         if (columnIndex < maxColumns - 1) {
+          // Column break within a multi-column layout: advance to next column.
+          // DO NOT snapshot note allocations — only page-push triggers snapshotting.
+          // Clear pending note state alongside reservedNotes so notes that only
+          // appeared before the column break don't get double-counted.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
         } else {
           pushPage(nextBoundary);
         }
@@ -1121,9 +1490,37 @@ function paginateSectionBlocksWithSplits(
             },
           ],
     splits: { byBlockId: splitsByBlock },
+    noteAllocationsByPageInSection,
+    noteFragmentsByPageInSection,
   };
 }
 
+/**
+ * Measure the height consumed by one note's body blocks, plus return those
+ * blocks for use in building a `RuntimeBlockFragment`.
+ *
+ * Factored out of `estimateFootnoteReservation` so both the reservation-math
+ * path and the P8.1b allocation-emission path share the same measurement.
+ */
+function measureNoteBody(
+  noteKind: "footnote" | "endnote",
+  noteId: string,
+  footnotes: FootnoteCollection,
+  columnWidth: number,
+): { heightTwips: number } {
+  const noteCollection =
+    noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
+  const note = noteCollection[noteId];
+  if (!note) {
+    return { heightTwips: 0 };
+  }
+  const heightTwips = note.blocks.reduce(
+    (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
+    0,
+  );
+  return { heightTwips };
+}
+
 function estimateFootnoteReservation(
   block: SurfaceBlockSnapshot,
   footnotes: FootnoteCollection | undefined,
@@ -1140,17 +1537,13 @@ function estimateFootnoteReservation(
       continue;
     }
 
-    const [noteKind, noteId] = noteKey.split(":");
-    const noteCollection =
-      noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
-    const note = noteCollection[noteId];
-    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS;
-    if (note) {
-      reservation += note.blocks.reduce(
-        (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
-        0,
-      );
-    }
+    const colonIdx = noteKey.indexOf(":");
+    if (colonIdx === -1) continue;
+    const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+    const noteId = noteKey.slice(colonIdx + 1);
+    // Use measureNoteBody so reservation math and emission share the same path.
+    const { heightTwips } = measureNoteBody(noteKind, noteId, footnotes, columnWidth);
+    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS + heightTwips;
   }
 
   return reservation;