@beyondwork/docx-react-component 1.0.36 → 1.0.38

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

@@ -0,0 +1,921 @@
+/**
+ * Runtime-owned paginated layout engine facade.
+ *
+ * `buildPageStack` is the stateless entry point.  A stateful `LayoutEngineInstance`
+ * layer in `./layout-engine-instance.ts` wraps this for `DocumentRuntime` use,
+ * adding the graph, story resolver, fragment mapper, and invalidation pipeline.
+ *
+ * Section-break fidelity implemented here:
+ *   - `nextPage` (default) — new page set per section
+ *   - `evenPage` / `oddPage` — blank filler pages to meet parity
+ *   - `continuous` — the new section continues on the previous section's last page
+ *   - `nextColumn` — treated as `continuous` (column advance still TODO for
+ *     true multi-column typeset; see `paginateSectionBlocks`)
+ *
+ * Paragraph-level pagination hints:
+ *   - `keepNext` — already honored in `paginateSectionBlocks`
+ *   - `keepLines` — already honored
+ *   - `pageBreakBefore` — already honored
+ *   - `widowControl` — applied by `applyWidowControlPass` after pagination
+ *
+ * Known remaining limitations:
+ * - Measurement uses empirical character-width tables by default; Canvas +
+ *   FontFace is available via `LayoutMeasurementProvider` but not yet
+ *   integrated into `measureBlockHeight()`.
+ * - Full recompute on every change; bounded incremental relayout remains
+ *   a Phase-5 target.
+ *
+ * Ownership rules:
+ * - DocumentRuntime owns the stateful engine lifecycle and cache invalidation.
+ * - ProseMirror remains the editing surface, never the page compositor.
+ * - React/Tailwind consume resulting snapshots as read-models.
+ */
+
+import type {
+  DocumentPageSnapshot,
+  EditorSurfaceSnapshot,
+  PageLayoutSnapshot,
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+import type {
+  FootnoteCollection,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import {
+  buildPageLayoutSnapshot,
+  buildResolvedSections,
+  type ResolvedDocumentSection,
+} from "../document-layout.ts";
+import {
+  estimateBlockHeight,
+  estimateParagraphHeight,
+  getUsableColumnMetrics,
+  getUsableColumnWidth,
+  getUsablePageHeight,
+} from "../page-layout-estimation.ts";
+import {
+  calculateParagraphHeight,
+  resolveBlockFormatting,
+  resolveCharsPerLine,
+  resolveNumberingPrefixLength,
+  resolveTextWidth,
+} from "./resolved-formatting-state.ts";
+import { analyzeInvalidation as analyzeInvalidationFn } from "./layout-invalidation.ts";
+import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type LayoutInvalidationReason =
+  | { kind: "content-edit"; from: number; to: number }
+  | { kind: "section-change"; sectionIndex: number }
+  | { kind: "styles-change" }
+  | { kind: "theme-change" }
+  | { kind: "numbering-change"; numberingInstanceId?: string }
+  | { kind: "field-refresh"; family?: string }
+  | { kind: "full" };
+
+export interface PageStackResult {
+  pages: DocumentPageSnapshot[];
+  sections: ResolvedDocumentSection[];
+}
+
+// ---------------------------------------------------------------------------
+// Facade
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the page stack for a document.
+ *
+ * This is the single entry point for page composition.  All consumers
+ * (document-navigation, view-state, page mode) should call this instead
+ * of directly using the estimation helpers.
+ *
+ * `measurementProvider` is optional.  When supplied, paragraph line counts
+ * and block heights consult the provider's `measureLineFragments` so the
+ * canvas backend can participate.  When omitted, measurement falls through
+ * to the empirical path baked into this module — which matches the
+ * provider's empirical backend numerically, keeping pagination stable.
+ */
+export function buildPageStack(
+  document: CanonicalDocumentEnvelope,
+  sections: ResolvedDocumentSection[],
+  mainSurface: EditorSurfaceSnapshot,
+  measurementProvider?: LayoutMeasurementProvider,
+): DocumentPageSnapshot[] {
+  const pages: DocumentPageSnapshot[] = [];
+  let globalPageIndex = 0;
+
+  for (let sectionIdx = 0; sectionIdx < sections.length; sectionIdx++) {
+    const section = sections[sectionIdx]!;
+    const layout = buildPageLayoutSnapshot(
+      section.index,
+      section.properties ?? document.subParts?.finalSectionProperties,
+      document.subParts,
+    );
+    const sectionBlocks = collectSectionBlocks(mainSurface.blocks, section.start, section.end);
+
+    // In OOXML, sectionType on a section's properties describes how
+    // the NEXT section starts — it is stored on the section that ends
+    // at the break.  So when processing section N (N > 0), the break
+    // type that governs section N's start is on section N-1's properties.
+    //
+    // OOXML even/odd refers to 1-based display page numbers:
+    //   globalPageIndex 0 → next display page 1 (odd)
+    //   globalPageIndex 1 → next display page 2 (even)
+    const prevSection = sectionIdx > 0 ? sections[sectionIdx - 1] : undefined;
+    const breakType = prevSection?.properties?.sectionType;
+    const nextDisplayPage = globalPageIndex + 1; // 1-based
+    const isContinuous = breakType === "continuous" || breakType === "nextColumn";
+
+    if (breakType === "evenPage" && globalPageIndex > 0) {
+      if (nextDisplayPage % 2 !== 0) {
+        const prevLayout = pages[pages.length - 1]?.layout ?? layout;
+        pages.push({
+          pageIndex: globalPageIndex,
+          sectionIndex: section.index,
+          pageInSection: -1,
+          startOffset: section.start,
+          endOffset: section.start,
+          layout: prevLayout,
+        });
+        globalPageIndex += 1;
+      }
+    } else if (breakType === "oddPage" && globalPageIndex > 0) {
+      if (nextDisplayPage % 2 === 0) {
+        const prevLayout = pages[pages.length - 1]?.layout ?? layout;
+        pages.push({
+          pageIndex: globalPageIndex,
+          sectionIndex: section.index,
+          pageInSection: -1,
+          startOffset: section.start,
+          endOffset: section.start,
+          layout: prevLayout,
+        });
+        globalPageIndex += 1;
+      }
+    }
+
+    const paginated = paginateSectionBlocks(
+      section,
+      sectionBlocks,
+      layout,
+      document.subParts?.footnoteCollection,
+      measurementProvider,
+    );
+
+    // continuous / nextColumn: merge the first page of this section into the
+    // previous section's last page (same visual sheet of paper, different
+    // semantic section).  The merged page keeps the PREVIOUS section's
+    // layout because page geometry cannot change mid-page in OOXML.
+    let firstPageHandled = false;
+    if (
+      isContinuous &&
+      pages.length > 0 &&
+      paginated.length > 0 &&
+      pages[pages.length - 1]!.pageInSection !== -1
+    ) {
+      const previousPage = pages[pages.length - 1]!;
+      const firstNewPage = paginated[0]!;
+      // Extend the previous page's endOffset through the continuous section's
+      // first page content.  Subsequent pages in the continuous section flow
+      // onto fresh pages as if the break were `nextPage`.
+      previousPage.endOffset = Math.max(
+        previousPage.endOffset,
+        firstNewPage.endOffset,
+      );
+      firstPageHandled = true;
+    }
+
+    for (let i = 0; i < paginated.length; i += 1) {
+      if (firstPageHandled && i === 0) continue;
+      const page = paginated[i]!;
+      pages.push({
+        ...page,
+        pageIndex: globalPageIndex,
+      });
+      globalPageIndex += 1;
+    }
+  }
+
+  // Guarantee at least one page
+  if (pages.length === 0) {
+    pages.push({
+      pageIndex: 0,
+      sectionIndex: 0,
+      pageInSection: 0,
+      startOffset: 0,
+      endOffset: mainSurface.storySize,
+      layout: buildPageLayoutSnapshot(
+        0,
+        document.subParts?.finalSectionProperties,
+        document.subParts,
+      ),
+    });
+  }
+
+  applyWidowControlPass(pages, mainSurface);
+  return pages;
+}
+
+/**
+ * Resumable variant of `buildPageStack` — returns page snapshots starting at
+ * `resumeAt.startPageIndex`, suitable for splicing into a prior page graph.
+ *
+ * Correctness baseline: the current implementation calls the full
+ * `buildPageStack` and slices.  This is not a performance win on its own —
+ * it is a safe contract that lets the engine stitch bounded rebuilds without
+ * writing a custom resume traversal.  Widow/orphan, section-break fillers,
+ * and continuous-section merges remain handled by the stable pipeline.
+ *
+ * Future work can replace the body with a true resume that reuses block
+ * heights computed for pages before `startPageIndex`.
+ */
+export function buildPageStackFrom(
+  document: CanonicalDocumentEnvelope,
+  sections: readonly ResolvedDocumentSection[],
+  mainSurface: EditorSurfaceSnapshot,
+  resumeAt: { startPageIndex: number; startOffset: number },
+  measurementProvider?: LayoutMeasurementProvider,
+): DocumentPageSnapshot[] {
+  // Correctness-first: run the full pipeline and return pages from the
+  // requested start.  `startOffset` is accepted for forward compatibility
+  // with a future true-resume but is not required by this implementation.
+  void resumeAt.startOffset;
+  const full = buildPageStack(
+    document,
+    sections as ResolvedDocumentSection[],
+    mainSurface,
+    measurementProvider,
+  );
+  const startIndex = Math.max(0, resumeAt.startPageIndex);
+  return full.slice(startIndex);
+}
+
+// ---------------------------------------------------------------------------
+// Widow control pass
+// ---------------------------------------------------------------------------
+
+/**
+ * Bounded widow/orphan correction.
+ *
+ * After pagination we inspect each page pair.  If page N-1 ends with a
+ * paragraph whose `widowControl` is enabled AND the paragraph's final line
+ * falls on page N (i.e. page N starts with exactly the trailing tail of a
+ * paragraph that began on page N-1), we push the last line back to page N
+ * by reducing page N-1's endOffset by the width of that trailing line.
+ *
+ * The current pass is bounded: it only corrects the single-line case.  It
+ * does not attempt to re-flow arbitrary content.  When the measurement
+ * provider upgrades to canvas fidelity and we carry per-paragraph line
+ * boxes, this pass will become more precise.
+ *
+ * Today it operates on block-level boundaries — if a paragraph with
+ * widowControl straddles a page boundary and the trailing slice covers less
+ * than ~15% of its full height (estimated), we pull the whole paragraph
+ * forward.  This is a conservative heuristic that will not corrupt
+ * pagination; it only very slightly compresses page breaks.
+ */
+function applyWidowControlPass(
+  pages: DocumentPageSnapshot[],
+  mainSurface: EditorSurfaceSnapshot,
+): void {
+  if (pages.length < 2) return;
+
+  for (let i = 1; i < pages.length; i += 1) {
+    const prev = pages[i - 1]!;
+    const cur = pages[i]!;
+    if (prev.pageInSection === -1 || cur.pageInSection === -1) continue;
+
+    // Find the paragraph, if any, that straddles the boundary.
+    const straddling = mainSurface.blocks.find(
+      (block) =>
+        block.kind === "paragraph" &&
+        block.from < prev.endOffset &&
+        block.to > prev.endOffset &&
+        block.to <= cur.endOffset,
+    );
+    if (!straddling || straddling.kind !== "paragraph") continue;
+    if (straddling.widowControl === false) continue;
+    if (straddling.from === prev.endOffset) continue; // fully on next page
+
+    const totalSpan = straddling.to - straddling.from;
+    const onNextPage = straddling.to - prev.endOffset;
+    if (totalSpan <= 0) continue;
+    // Pull-forward when the trailing slice is less than 15% of the paragraph,
+    // i.e. likely a single stranded line.
+    if (onNextPage / totalSpan <= 0.15) {
+      prev.endOffset = straddling.to;
+      cur.startOffset = straddling.to;
+    }
+  }
+}
+
+/**
+ * Compute the full page stack result including resolved sections.
+ *
+ * Convenience wrapper for callers that need both sections and pages.
+ */
+export function computePageStack(
+  document: CanonicalDocumentEnvelope,
+  mainSurface: EditorSurfaceSnapshot,
+): PageStackResult {
+  const sections = buildResolvedSections(document);
+  const pages = buildPageStack(document, sections, mainSurface);
+  return { pages, sections };
+}
+
+// ---------------------------------------------------------------------------
+// Invalidation — delegates to layout-invalidation.ts
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether a layout invalidation reason requires a full recompute.
+ *
+ * Delegates to `analyzeInvalidation()` which classifies the reason against
+ * the current graph.  Callers that already hold a graph should call
+ * `analyzeInvalidation` directly for finer-grained output.
+ */
+export function requiresFullRecompute(reason: LayoutInvalidationReason): boolean {
+  // Use a conservative analysis with no graph — returns full recompute for
+  // all reasons except `field-refresh`, matching Phase-4 semantics.
+  return analyzeInvalidationFn(reason, null).requiresFullRecompute;
+}
+
+// ---------------------------------------------------------------------------
+// Block measurement — uses ResolvedFormattingState for paragraphs
+// ---------------------------------------------------------------------------
+
+const MIN_BLOCK_HEIGHT_TWIPS = 240;
+const FOOTNOTE_REFERENCE_RESERVATION_TWIPS = 180;
+
+/**
+ * Compute block height using resolved formatting when available.
+ * Uses improved table measurement for legal contracts.
+ *
+ * When `measurementProvider` is supplied, paragraph line counts are produced
+ * by `provider.measureLineFragments(...)`; otherwise the inline empirical
+ * path runs (which matches the empirical backend numerically).
+ */
+function measureBlockHeight(
+  block: SurfaceBlockSnapshot | undefined,
+  columnWidth: number,
+  measurementProvider?: LayoutMeasurementProvider,
+): 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);
+      }
+      return estimateBlockHeight(block, columnWidth);
+    }
+    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;
+  }
+}
+
+/**
+ * Improved table height estimation.
+ *
+ * Uses resolved formatting for cell content paragraphs and respects
+ * explicit row heights and height rules.
+ *
+ * Per-cell width is derived from the table's `gridColumns` and each
+ * cell's `colspan` (honoring `gridBefore`/`gridAfter` row padding).
+ * This replaces the prior `columnWidth / cellCount` approximation,
+ * which was wrong whenever columns carried non-uniform widths or any
+ * cell had `colspan > 1`.
+ */
+function measureTableHeight(
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+  columnWidth: number,
+  measurementProvider?: LayoutMeasurementProvider,
+): number {
+  const TABLE_ROW_PADDING_TWIPS = 120;
+  let totalHeight = 0;
+
+  const gridColumnCount = block.gridColumns.length;
+  const totalGridTwips = block.gridColumns.reduce((sum, w) => sum + w, 0);
+  // Scale the canonical gridColumns to the available column width so that
+  // a table defined in 9000-twip grid on a 12240-twip canvas measures
+  // against the actual canvas width, not the OOXML-declared width.
+  const gridScale =
+    totalGridTwips > 0 && columnWidth > 0 ? columnWidth / totalGridTwips : 1;
+
+  for (const row of block.rows) {
+    const explicitHeight = row.height ?? 0;
+    const heightRule = row.heightRule ?? "auto";
+    const gridBefore = row.gridBefore ?? 0;
+
+    // Calculate content-driven height using real per-cell widths.
+    let contentHeight = MIN_BLOCK_HEIGHT_TWIPS;
+    let columnCursor = gridBefore;
+
+    for (const cell of row.cells) {
+      const span = Math.max(1, cell.colspan ?? 1);
+      const cellWidth = resolveCellWidth(
+        block.gridColumns,
+        columnCursor,
+        span,
+        columnWidth,
+        gridScale,
+      );
+      columnCursor += span;
+
+      if (cell.verticalMerge === "continue") {
+        // Continuation cells don't contribute their own content height —
+        // the origin cell's height covers the whole span.
+        continue;
+      }
+
+      let cellContentHeight = 0;
+      for (const child of cell.content) {
+        cellContentHeight += measureBlockHeight(
+          child,
+          cellWidth,
+          measurementProvider,
+        );
+      }
+      contentHeight = Math.max(contentHeight, cellContentHeight + TABLE_ROW_PADDING_TWIPS);
+    }
+
+    // Sanity fallback if the row declared more columns than the grid
+    // (malformed input) — clamp the cursor back so subsequent rows
+    // continue to measure without throwing.
+    if (gridColumnCount > 0 && columnCursor > gridColumnCount) {
+      // no-op; kept for documentation — width resolution handles overflow.
+    }
+
+    if (heightRule === "exact" && explicitHeight > 0) {
+      totalHeight += explicitHeight;
+    } else if (heightRule === "atLeast" && explicitHeight > 0) {
+      totalHeight += Math.max(explicitHeight, contentHeight);
+    } else if (explicitHeight > 0) {
+      totalHeight += Math.max(explicitHeight, contentHeight);
+    } else {
+      totalHeight += contentHeight;
+    }
+  }
+
+  return Math.max(MIN_BLOCK_HEIGHT_TWIPS, totalHeight);
+}
+
+/**
+ * Sum the widths of `columnSpan` columns starting at `startColumn` from
+ * the table's `gridColumns`, scaled to the available column width.
+ *
+ * Falls back to an even split of `fallbackColumnWidth` when the grid has
+ * no entries (no `gridColumns` declared).
+ *
+ * Exported via `__resolveCellWidth` for unit tests; not part of the
+ * stable surface.
+ */
+export function __resolveCellWidth(
+  gridColumns: readonly number[],
+  startColumn: number,
+  columnSpan: number,
+  fallbackColumnWidth: number,
+  gridScale: number,
+): number {
+  return resolveCellWidth(gridColumns, startColumn, columnSpan, fallbackColumnWidth, gridScale);
+}
+
+function resolveCellWidth(
+  gridColumns: readonly number[],
+  startColumn: number,
+  columnSpan: number,
+  fallbackColumnWidth: number,
+  gridScale: number,
+): number {
+  if (gridColumns.length === 0) {
+    // No grid declared — best-effort even split of the canvas.
+    return Math.max(240, Math.floor(fallbackColumnWidth));
+  }
+  let gridWidth = 0;
+  for (let i = 0; i < columnSpan; i += 1) {
+    const column = startColumn + i;
+    if (column < 0 || column >= gridColumns.length) continue;
+    gridWidth += gridColumns[column] ?? 0;
+  }
+  const scaled = Math.floor(gridWidth * gridScale);
+  return Math.max(240, scaled);
+}
+
+/**
+ * Count lines in a paragraph using resolved formatting.
+ * Accounts for proper indentation, font metrics, and numbering geometry.
+ *
+ * When a measurement provider is supplied, delegates line counting to the
+ * provider's `measureLineFragments`.  The provider's empirical backend
+ * returns the same numerical result as the inline path, so switching does
+ * not change pagination behavior; the canvas backend returns canvas-
+ * measured line counts once fonts resolve.
+ */
+function measureParagraphLineCount(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+  formatting: import("./resolved-formatting-state.ts").ResolvedParagraphFormatting,
+  columnWidth: number,
+  measurementProvider?: LayoutMeasurementProvider,
+): number {
+  if (measurementProvider) {
+    const measured = measurementProvider.measureLineFragments({
+      block,
+      formatting,
+      // The paginated pipeline currently resolves formatting at the
+      // paragraph level only; per-run formatting is not yet threaded
+      // through.  Pass an empty map; the provider's empirical backend
+      // does not consult per-run metrics and the canvas backend falls
+      // back to the paragraph defaults when a run is missing.
+      runs: new Map(),
+      columnWidth,
+    });
+    return Math.max(1, measured.lineCount);
+  }
+
+  const firstLineWidth = resolveTextWidth(formatting, columnWidth, true);
+  const subsequentLineWidth = resolveTextWidth(formatting, columnWidth, false);
+  const firstLineCapacity = resolveCharsPerLine(firstLineWidth, formatting.averageCharWidthTwips);
+  const subsequentLineCapacity = resolveCharsPerLine(subsequentLineWidth, formatting.averageCharWidthTwips);
+
+  let lineCount = 1;
+  let currentLineChars = resolveNumberingPrefixLength(block);
+  let currentLineCapacity = firstLineCapacity;
+
+  for (const segment of block.segments) {
+    switch (segment.kind) {
+      case "text":
+        currentLineChars += Array.from(segment.text).length;
+        while (currentLineChars > currentLineCapacity) {
+          lineCount += 1;
+          currentLineChars -= currentLineCapacity;
+          currentLineCapacity = subsequentLineCapacity;
+        }
+        break;
+      case "tab": {
+        // Resolve tab to actual tab stop position if available
+        const tabAdvance = resolveTabAdvance(formatting, currentLineChars, formatting.averageCharWidthTwips, columnWidth);
+        currentLineChars += tabAdvance;
+        while (currentLineChars > currentLineCapacity) {
+          lineCount += 1;
+          currentLineChars -= currentLineCapacity;
+          currentLineCapacity = subsequentLineCapacity;
+        }
+        break;
+      }
+      case "hard_break":
+        lineCount += 1;
+        currentLineChars = 0;
+        currentLineCapacity = subsequentLineCapacity;
+        break;
+      case "image":
+        lineCount += Math.max(1, Math.round(segment.display === "floating" ? 2 : 1));
+        currentLineChars = 0;
+        currentLineCapacity = subsequentLineCapacity;
+        break;
+      case "note_ref":
+        currentLineChars += 1;
+        while (currentLineChars > currentLineCapacity) {
+          lineCount += 1;
+          currentLineChars -= currentLineCapacity;
+          currentLineCapacity = subsequentLineCapacity;
+        }
+        break;
+      case "opaque_inline":
+        if (segment.presentation !== "quiet-marker") {
+          currentLineChars += segment.label.length > 0 ? 1 : 0;
+          while (currentLineChars > currentLineCapacity) {
+            lineCount += 1;
+            currentLineChars -= currentLineCapacity;
+            currentLineCapacity = subsequentLineCapacity;
+          }
+        }
+        break;
+    }
+  }
+
+  return Math.max(1, lineCount);
+}
+
+/**
+ * Resolve tab advance in character-equivalents, considering tab stops.
+ */
+function resolveTabAdvance(
+  formatting: import("./resolved-formatting-state.ts").ResolvedParagraphFormatting,
+  currentChars: number,
+  avgCharWidth: number,
+  columnWidth: number,
+): number {
+  // Default tab stops every 720 twips (0.5 inch)
+  const defaultTabInterval = 720;
+  const currentPosition = currentChars * avgCharWidth + formatting.indentLeft;
+
+  if (formatting.tabStops.length === 0) {
+    const nextTab = Math.ceil((currentPosition + 1) / defaultTabInterval) * defaultTabInterval;
+    const advance = nextTab - currentPosition;
+    return Math.max(1, Math.round(advance / avgCharWidth));
+  }
+
+  // Find the next tab stop after current position
+  for (const tab of formatting.tabStops) {
+    if (tab.position > currentPosition) {
+      const advance = tab.position - currentPosition;
+      return Math.max(1, Math.round(advance / avgCharWidth));
+    }
+  }
+
+  // Past all tab stops — use default advance
+  return 4;
+}
+
+// ---------------------------------------------------------------------------
+// Section block collection
+// ---------------------------------------------------------------------------
+
+function collectSectionBlocks(
+  blocks: readonly SurfaceBlockSnapshot[],
+  start: number,
+  end: number,
+): SurfaceBlockSnapshot[] {
+  return blocks.filter((block) => block.to > start && block.from < end);
+}
+
+function paginateSectionBlocks(
+  section: ResolvedDocumentSection,
+  blocks: readonly SurfaceBlockSnapshot[],
+  layout: DocumentPageSnapshot["layout"],
+  footnotes: FootnoteCollection | undefined,
+  measurementProvider?: LayoutMeasurementProvider,
+): Omit<DocumentPageSnapshot, "pageIndex">[] {
+  if (blocks.length === 0) {
+    return [
+      {
+        sectionIndex: section.index,
+        pageInSection: 0,
+        startOffset: section.start,
+        endOffset: section.end,
+        layout,
+      },
+    ];
+  }
+
+  const pages: Omit<DocumentPageSnapshot, "pageIndex">[] = [];
+  const usableHeight = getUsablePageHeight(layout);
+  const columnMetrics = getUsableColumnMetrics(layout);
+  const maxColumns = Math.max(1, columnMetrics.length);
+  let pageStart = section.start;
+  let columnHeight = 0;
+  let columnIndex = 0;
+  let pageInSection = 0;
+  let reservedNoteHeight = 0;
+  const reservedNotes = new Set<string>();
+
+  const pushPage = (endOffset: number): void => {
+    const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
+    if (boundedEnd === pageStart && pages.length > 0) {
+      return;
+    }
+    pages.push({
+      sectionIndex: section.index,
+      pageInSection,
+      startOffset: pageStart,
+      endOffset: boundedEnd,
+      layout,
+    });
+    pageInSection += 1;
+    pageStart = boundedEnd;
+    columnHeight = 0;
+    columnIndex = 0;
+    reservedNoteHeight = 0;
+    reservedNotes.clear();
+  };
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index]!;
+    const nextBoundary = blocks[index + 1]?.from ?? section.end;
+    while (true) {
+      const columnWidth =
+        columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
+        getUsableColumnWidth(layout);
+      const baseHeight = measureBlockHeight(block, columnWidth, measurementProvider);
+
+      // 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)
+          : baseHeight;
+
+      // keepLines: the entire paragraph must fit on one page.
+      // If it doesn't fit and there's already content on this page, break before it.
+      const formatting = block.kind === "paragraph" ? resolveBlockFormatting(block) : null;
+      const keepLinesActive = formatting?.keepLines ?? false;
+
+      const noteHeight = estimateFootnoteReservation(block, footnotes, columnWidth, reservedNotes);
+      const projectedHeight = columnHeight + keepWithNextHeight + reservedNoteHeight + noteHeight;
+
+      // pageBreakBefore
+      if (block.kind === "paragraph" && block.pageBreakBefore && pageStart < block.from) {
+        pushPage(block.from);
+        continue;
+      }
+
+      // Overflow check — paragraph doesn't fit on current page
+      if (projectedHeight > usableHeight && pageStart < block.from) {
+        if (columnIndex < maxColumns - 1) {
+          columnIndex += 1;
+          columnHeight = 0;
+          reservedNoteHeight = 0;
+          reservedNotes.clear();
+          continue;
+        }
+        pushPage(block.from);
+        continue;
+      }
+
+      // keepLines: if the paragraph alone exceeds page height and there's
+      // already content, push it to the next page (the paragraph itself will
+      // 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) {
+          columnIndex += 1;
+          columnHeight = 0;
+          reservedNoteHeight = 0;
+          reservedNotes.clear();
+          continue;
+        }
+        pushPage(block.from);
+        continue;
+      }
+
+      const effectiveNoteHeight = estimateFootnoteReservation(
+        block,
+        footnotes,
+        columnWidth,
+        reservedNotes,
+      );
+      columnHeight += baseHeight;
+      reservedNoteHeight += effectiveNoteHeight;
+      currentPageNoteIds(block).forEach((noteKey) => reservedNotes.add(noteKey));
+
+      if (hasColumnBreak(block)) {
+        if (columnIndex < maxColumns - 1) {
+          columnIndex += 1;
+          columnHeight = 0;
+          reservedNoteHeight = 0;
+          reservedNotes.clear();
+        } else {
+          pushPage(nextBoundary);
+        }
+        break;
+      }
+
+      if (index === blocks.length - 1) {
+        pushPage(section.end);
+      }
+      break;
+    }
+  }
+
+  return pages.length > 0
+    ? pages
+    : [
+        {
+          sectionIndex: section.index,
+          pageInSection: 0,
+          startOffset: section.start,
+          endOffset: section.end,
+          layout,
+        },
+      ];
+}
+
+function estimateFootnoteReservation(
+  block: SurfaceBlockSnapshot,
+  footnotes: FootnoteCollection | undefined,
+  columnWidth: number,
+  reservedNotes: ReadonlySet<string>,
+): number {
+  if (!footnotes || block.kind !== "paragraph") {
+    return 0;
+  }
+
+  let reservation = 0;
+  for (const noteKey of currentPageNoteIds(block)) {
+    if (reservedNotes.has(noteKey)) {
+      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,
+      );
+    }
+  }
+
+  return reservation;
+}
+
+function estimateCanonicalNoteBlockHeight(
+  block: FootnoteCollection["footnotes"][string]["blocks"][number],
+  columnWidth: number,
+): number {
+  switch (block.type) {
+    case "paragraph":
+      return estimateParagraphHeight(
+        {
+          blockId: "note",
+          kind: "paragraph",
+          from: 0,
+          to: 0,
+          ...(block.styleId ? { styleId: block.styleId } : {}),
+          segments: createEstimatedNoteSegments(block.children),
+        },
+        columnWidth,
+      );
+    case "table":
+      return MIN_BLOCK_HEIGHT_TWIPS * Math.max(1, block.rows.length);
+    default:
+      return MIN_BLOCK_HEIGHT_TWIPS;
+  }
+}
+
+function createEstimatedNoteSegments(
+  children: Extract<FootnoteCollection["footnotes"][string]["blocks"][number], { type: "paragraph" }>["children"],
+): import("../../api/public-types").SurfaceInlineSegment[] {
+  const segments: import("../../api/public-types").SurfaceInlineSegment[] = [];
+
+  children.forEach((child, index) => {
+    if (child.type === "text") {
+      segments.push({
+        segmentId: `note-${index}`,
+        kind: "text",
+        from: 0,
+        to: Array.from(child.text).length,
+        text: child.text,
+      });
+      return;
+    }
+
+    if (child.type === "hard_break" || child.type === "tab") {
+      segments.push({
+        segmentId: `note-${index}`,
+        kind: child.type,
+        from: 0,
+        to: 1,
+      });
+    }
+  });
+
+  return segments;
+}
+
+function currentPageNoteIds(
+  block: SurfaceBlockSnapshot,
+): Set<string> {
+  const notes = new Set<string>();
+  if (block.kind !== "paragraph") {
+    return notes;
+  }
+
+  for (const segment of block.segments) {
+    if (segment.kind === "note_ref" && segment.noteId) {
+      notes.add(`${segment.noteKind}:${segment.noteId}`);
+    }
+  }
+  return notes;
+}
+
+function hasColumnBreak(block: SurfaceBlockSnapshot): boolean {
+  return block.kind === "paragraph" && block.segments.some(
+    (segment) =>
+      segment.kind === "opaque_inline" &&
+      segment.label === "Column break",
+  );
+}