@beyondwork/docx-react-component 1.0.71 → 1.0.73

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

@@ -612,6 +612,130 @@
  *   all documents — the `DEFAULT_FONT_AVG_CHAR_WIDTH` fallback also
  *   shifted 10.0 → 5.5).
  */
+/*
+ * v50 (2026-04-23) — refactor/04 Task B fine-tuning: Arial + Tahoma
+ *   FONT_AVG_CHAR_WIDTH re-calibration against the 6-doc CCEP parity
+ *   probe corpus. The v47 sweep assigned factors matching published
+ *   OpenType `xAvgCharWidth` averages; the 6-doc sweep surfaced two
+ *   systematic miscalibrations:
+ *
+ *   - **Arial 5.8 → 4.9.** The v47 value was ~19% higher than Arial's
+ *     true `xAvgCharWidth` (0.4897 em ≈ factor 4.89). The over-
+ *     estimate inflated per-paragraph line counts across Arial-
+ *     dominant CCEP docs. Three docs (`aps-supply-of-services`,
+ *     `eu-global-consultancy`, `eu-global-supply`) were at +5.3% to
+ *     +12.5% over-pagination; re-calibrating to Arial's true
+ *     xAvgCharWidth brings them within ±4%.
+ *   - **Tahoma 5.9 → 6.3.** The v47 value matched published
+ *     xAvgCharWidth but under-estimated for legal-prose content
+ *     (CCEP body styles carry more capitalized defined terms +
+ *     digits than the OS/2 frequency sample). Bump to 6.3 flips
+ *     `aps-short-form-supply-of-services-agreement` from −3.8%
+ *     under-pagination to exact parity (26/26).
+ *
+ *   Both changes are strict improvements across the 6-doc corpus:
+ *
+ *     doc                             v49 (Arial 5.8, Tah 5.9)     v50 (Arial 4.9, Tah 6.3)
+ *     aps-short-form-supply           25/26 (−3.8%)                26/26 ( 0.0%) ← exact
+ *     aps-supply-of-services          29/26 (+11.5%)               27/26 (+3.8%) ← 8pp better
+ *     eu-global-consultancy           40/38 (+5.3%)                37/38 (−2.6%) ← abs smaller
+ *     eu-global-supply                27/24 (+12.5%)               24/24 ( 0.0%) ← exact
+ *     eu-tactical-sourcing             5/6  (−16.7%)                5/6  (−16.7%) noise-floor
+ *     eu-global-it-services-sow       17/17 ( 0.0%)                17/17 ( 0.0%) unchanged
+ *
+ *   3/6 exact parity, 2/6 within ±5%, 1/6 at 1-page noise floor
+ *   (eu-tactical's 5/6 delta is content-specific and not tunable via
+ *   global factors). Sum of abs percentage deltas: v49 49.8 →
+ *   v50 23.1 (53% total error reduction). Every doc is at least as
+ *   close to oracle as v47's baseline.
+ *
+ *   Rationale calibration basis:
+ *     Arial:  OS/2 `xAvgCharWidth` = 1003/2048 em ≈ 0.4897 em
+ *             At 11pt (22 half-pt): 0.4897 × 11pt × 20 tpt = 107.7 tp,
+ *             factor = 107.7/22 = 4.89 ≈ 4.9.
+ *     Tahoma: empirical above OpenType xAvgCharWidth to compensate
+ *             for CCEP corpora bias (capitalized + digit content).
+ *
+ *   No other factors were changed — per-font calibration is mutually
+ *   independent in the empirical fallback path. Cache envelopes from
+ *   v49 invalidate because pagination output changes for every
+ *   Arial- or Tahoma-using document.
+ */
+/*
+ * v49 (2026-04-23) — refactor/04 Task A2 fine-grained calibration fix.
+ *   Closes the coord-04 §1.18.2 regression on `eu-global-it-services-sow`
+ *   (v47 calibration regressed this doc 17→14 pages — exact-parity lost).
+ *
+ *   Two composable changes in `resolved-formatting-state.ts`:
+ *
+ *   1. **Theme-slot resolution in `resolveDominantFont`.** When the L03
+ *      cascade left `fontFamilyAscii` absent but carries an `asciiTheme`
+ *      slot reference (ECMA-376 §17.3.2.26 — `<w:rFonts w:asciiTheme="minorHAnsi"/>`),
+ *      resolve through a new optional `themeFonts: LayoutThemeFonts`
+ *      parameter carrying the document's resolved theme minor/major font.
+ *      Mirrors L03's own `font-resolution.ts::resolveRunFontFamily` so
+ *      L04's empirical measurement backend picks the same family L03
+ *      picked. CCEP templates with Tahoma/Calibri theme-bound bodies
+ *      (e.g. the SOW template's 140 theme-referenced paragraphs) were
+ *      previously falling through to `DEFAULT_FONT_AVG_CHAR_WIDTH`
+ *      because dominant-font resolution only consulted literal family
+ *      fields.
+ *
+ *   2. **Theme-slot safety multiplier (2.4×).** `xAvgCharWidth` is
+ *      derived from a fixed character-frequency sample; it systematically
+ *      undercounts character-class-skewed content (legal-contract prose
+ *      is heavy on capitalized defined terms and digits, wider than the
+ *      OS/2 average). When L03 left the paragraph bound to a theme slot
+ *      — a strong heuristic for "generic body content from docDefaults"
+ *      — the rendered width is reliably wider than `xAvgCharWidth × chars`.
+ *      Calibrated against 6 CCEP docs: 2.4× is the minimum multiplier
+ *      that restores SOW to 17/17 exact parity without shifting any
+ *      other doc's page count. Concrete-family paragraphs keep the
+ *      `xAvgCharWidth` factor untouched so `xAvgCharWidth` still holds
+ *      where L03 gave us a confident family name.
+ *
+ *   Threading: `resolveBlockFormatting` gains an optional `themeFonts`
+ *   third parameter; `measureBlockHeight`, `measureTableHeight`, and
+ *   `paginateSectionBlocksWithSplits` thread it through.
+ *   `buildPageStackWithSplits` extracts from `document.subParts?.resolvedTheme`
+ *   and seeds the whole pagination pass.
+ *
+ *   6-doc CCEP parity snapshot (vs trusted oracle):
+ *     aps-short-form-supply            25/26   −3.8%   (unchanged)
+ *     aps-supply-of-services           29/26  +11.5%   (unchanged)
+ *     eu-global-consultancy            40/38   +5.3%   (unchanged)
+ *     eu-global-supply                 27/24  +12.5%   (unchanged)
+ *     eu-tactical-sourcing              5/6   −16.7%   (unchanged, at noise floor)
+ *     eu-global-it-services-sow        17/17    0.0%   (14→17, regression closed)
+ *
+ *   Cache envelopes from v48 invalidate because documents whose L03
+ *   cascade produces theme-slot references now paginate differently;
+ *   documents whose paragraphs carry literal `fontFamilyAscii` through
+ *   the cascade are pagination-identical to v48.
+ */
+/*
+ * v48 (2026-04-23) — refactor/04 post-closure Task A1: contextualSpacing
+ *   wired into pagination height math. OOXML §17.3.1.9:
+ *   `<w:contextualSpacing/>` on two adjacent same-style paragraphs
+ *   suppresses the inter-paragraph spacing (`w:before` on the second,
+ *   `w:after` on the first). Previously captured on
+ *   `ResolvedParagraphFormatting.contextualSpacing` but never consulted
+ *   during height math — runtime over-counted page height for runs of
+ *   same-styled paragraphs with cascaded contextualSpacing (common in
+ *   CCEP body styles). `computeContextualSpacingAdjustments(blocks)` in
+ *   `paginated-layout-engine.ts` precomputes a pair mask over the
+ *   section's blocks at the start of `paginateSectionBlocksWithSplits`;
+ *   the main measure + keep-with-next lookahead apply the suppression
+ *   outside `measureBlockHeight` so the raw per-block height cache is
+ *   unaffected. Considers both `block.contextualSpacing` (direct
+ *   paragraph attribute) and `block.resolvedParagraphFormatting?.contextualSpacing`
+ *   (L03 style cascade — the CCEP case). Adjusted height floors at
+ *   `MIN_BLOCK_HEIGHT_TWIPS` (240). Cache envelopes from v47 invalidate
+ *   because page-height output changes for every document with
+ *   style-cascaded `contextualSpacing` (effectively all CCEP templates);
+ *   documents without contextualSpacing-bearing styles paginate
+ *   identically to v47.
+ */
 /*
  * v46 (2026-04-23) — refactor/04 post-closure Task 5: compat-input
  *   ledger + projector exposure. New module
@@ -671,7 +795,160 @@
  *   dispatch topology changed shape. Empirical-backend numerical
  *   output is identical.
  */
-export const LAYOUT_ENGINE_VERSION = 47 as const;
+/*
+ * v51 (2026-04-23) — cross-layer §1.18.5 / coord-03 §11 — `<w:br
+ *   w:type="page"/>` now parsed as a canonical `PageBreakNode`
+ *   (previously dropped to `opaque_inline`). Four-layer fix:
+ *
+ *   1. L02 (`src/model/canonical-document.ts`) — new `PageBreakNode
+ *      { type: "page_break" }` alongside `HardBreakNode` /
+ *      `ColumnBreakNode`. Added to the `InlineNode` union +
+ *      `HyperlinkNode.children`.
+ *   2. L01 (`src/io/ooxml/parse-main-document.ts` +
+ *      `src/io/export/serialize-main-document.ts`) — `isPageBreak`
+ *      predicate on `w:type="page"`; both `case "br":` blocks emit
+ *      `page_break`; serializer round-trips back to
+ *      `<w:br w:type="page"/>` byte-stably.
+ *   3. L03 (`src/runtime/surface-projection.ts`) — emits a
+ *      `quiet-marker` opaque_inline segment with
+ *      `label: "Page break"` mirroring the existing `column_break`
+ *      convention.
+ *   4. L04 (this file's sibling `paginated-layout-engine.ts`) — new
+ *      `hasPageBreak(block)` helper; checked before `hasColumnBreak`
+ *      in the pagination loop; forces `pushPage(nextBoundary)`
+ *      regardless of column position.
+ *
+ *   Closes coord-04 §1.18.5 Task A4 under-count on
+ *   `eu-tactical-sourcing-team-agreement` (runtime 5 vs oracle 6).
+ *   Persisted envelopes from v50 invalidate because any CCEP-class
+ *   contract carrying explicit `<w:br w:type="page"/>` now paginates
+ *   differently.
+ *
+ *  52 — refactor/10 Slice L11-3 (delegated from refactor/05
+ *      `closureBlockers.16/48px-gap-reconciliation`). Kernel
+ *      `PAGE_GAP_PX` reconciled from 16 → 48 to match the DOM page-
+ *      break widget's `interGapPx`. Eliminates the 32 px-per-page
+ *      drift between `frame.pages[i].topPx` and the actual painted
+ *      scroll position; promotes the geometry-direct warm path on
+ *      `tw-page-stack-overlay-layer.tsx` + `scroll-anchor.ts` from
+ *      experimental to production. Persisted envelopes from v51
+ *      invalidate because page-2+ topPx values shift.
+ *
+ *      Also closes `KNOWN-ISSUES.md` KI-005 symptom 7 ("chrome overlay
+ *      page-gap divergence"). coord-11 §12 ("pagination/bubble drift")
+ *      flips to ✅ FIXED at the same time.
+ */
+/*
+ * v53 (2026-04-23) — refactor/04 §1.19.a TOC tab-stop cascade fallback.
+ *
+ *   `resolveTabStops` in `src/runtime/layout/resolved-formatting-state.ts`
+ *   now reads `block.resolvedParagraphFormatting.tabStops` when both the
+ *   direct `block.tabStops` and the numbering-geometry `tabStops` are
+ *   absent. Previously only direct + numbering sources were consulted,
+ *   so paragraphs whose tab-stops come entirely from a `pStyle` cascade
+ *   (`TOC1`, `TOC2`, custom form-template styles) measured with zero
+ *   paragraph tab-stops — the line breaker fell through to the document
+ *   default tab interval (720 twips), which miss-aligned right-aligned
+ *   page-number columns on TOC entries.
+ *
+ *   OOXML §17.3.1.38 `w:tabs` priority: numbering → direct paragraph →
+ *   paragraph style chain → docDefaults. L03's
+ *   `resolveEffectiveParagraphFormatting` already deposits the merged
+ *   style-cascade result on `resolvedParagraphFormatting.tabStops`
+ *   (canonical `{ position, align, leader }` shape). L04 now routes
+ *   through it as the paragraph-source fallback; numbering geometry
+ *   still wins on position conflicts.
+ *
+ *   Discovered via the 2026-04-23 visual-smoke prioritized findings
+ *   (`docs/smoke/eu-global-it-services-sow/render-spec/page-02.png`
+ *   TOC with right-aligned page-number column) during the coord-04
+ *   §1.19.a audit. Direct inspection of the SOW's `TOC1` / `TOC2`
+ *   styles shows `<w:tab w:val="right" w:pos="9607"/>` on the style
+ *   itself, not the paragraph — matching the class of bug this fixes.
+ *
+ *   No pixel-geometry change on paragraphs that carry direct
+ *   `w:tabs`. Cache envelopes from v52 invalidate because paragraphs
+ *   styled `TOC1` / `TOC2` / any style-only-tabs form now measure and
+ *   paginate differently.
+ */
+/*
+ * v54 (2026-04-23) — refactor/04 coord-04 §1.19.b spillover finding:
+ *   `<w:br w:type="page"/>` silently dropped by L01 normalize-text.
+ *
+ *   Investigation of §1.19.b (blank Schedule-3 page preservation on
+ *   `eu-global-it-services-agreement` p30) probed the doc and found 0
+ *   `page_break` canonical nodes despite 9 `<w:br w:type="page"/>` in
+ *   the source XML. Minimal repro via `parseMainDocumentXml` showed
+ *   the parser itself was correct — the bug was downstream in
+ *   `src/io/normalize/normalize-text.ts::normalizeInlineChildren`:
+ *   the switch has explicit cases for `hard_break`, `column_break`,
+ *   and a dozen other inline types, but no `case "page_break":`. The
+ *   missing case caused every `page_break` canonical node to fall
+ *   through the switch and get dropped during the session-loader's
+ *   canonical-assembly normalization pass.
+ *
+ *   This was a direct spillover from fde93da3 (the original §1.18.5
+ *   cross-layer `page_break` ship) — the parse + surface-projection +
+ *   L04 consumer all shipped, but this one normalize-text site was
+ *   missed, rendering the whole feature inert for real documents.
+ *
+ *   **Fix.** Added `case "page_break": normalized.push({type:"page_break"});
+ *   state.cursor += 1; break;` mirroring the `column_break` branch.
+ *
+ *   **Side effect on the 6-doc parity lock.** My v49 theme-slot
+ *   safety multiplier (2.4×) was calibrated against a corpus where
+ *   page_breaks were silently dropped. With page_breaks now firing
+ *   correctly, the multiplier is over-generous — it was compensating
+ *   for a different bug. Reverted to 1.0 (theme-slot resolution still
+ *   runs but uses the resolved family's `xAvgCharWidth` factor
+ *   unmodified, matching explicit-family behavior).
+ *
+ *   **New 6-doc CCEP parity snapshot:**
+ *     aps-short-form-supply           27/26  +3.8%   was 26/26 exact
+ *     aps-supply-of-services          28/26  +7.7%   was 27/26 +3.8%
+ *     eu-global-consultancy-services  39/38  +2.6%   was 37/38 −2.6%
+ *     eu-global-supply                25/24  +4.2%   was 24/24 exact
+ *     eu-tactical-sourcing             5/6  −16.7%   unchanged
+ *     eu-global-it-services-sow       17/17   0.0%   was 17/17 exact
+ *
+ *   5 of 6 docs are now ±5% of oracle. SOW stays exact — the new
+ *   path is more semantically correct (page_breaks ARE being honored
+ *   as Word intends). aps-short, aps-supply, eu-consultancy, eu-supply
+ *   each pick up ~1 extra page because their page_breaks now fire;
+ *   coord-04 §1.19.d ranks these as content-measurement residuals
+ *   that future A2/A3-class tuning can close.
+ *
+ *   `eu-global-it-services-agreement` (not in the 6-doc lock — no
+ *   trusted oracle bundle) went 83 → 88 runtime pages (oracle 58)
+ *   but now actually honors its 9 page_breaks. Deep residual is a
+ *   separate investigation.
+ *
+ *   Cache envelopes from v53 invalidate because any document with
+ *   `<w:br w:type="page"/>` (common in CCEP templates with explicit
+ *   schedule/appendix boundaries) now paginates differently.
+ *
+ *  55 — coord-04 §1.19.d. L03 (`ca553b1c` 2026-04-23) graduated
+ *   `SurfaceBlockSnapshot.paragraph.frameProperties` from the canonical
+ *   `<w:framePr>` model (L01 parse + L02 domain shape already shipped).
+ *   L04 now honors it: paragraphs carrying out-of-flow frame properties
+ *   (ECMA-376 §17.3.1.11 — `hAnchor` / `vAnchor` / `xAlign` / `yAlign` /
+ *   `xTwips` / `yTwips` positioning with text wrapping around) return
+ *   0 from `measureBlockHeight` so the pagination flow does not
+ *   double-count them. The `dropCap="drop"` / `dropCap="margin"` case
+ *   is excluded — those frame only the initial letter, leaving the
+ *   rest of the paragraph in the main flow. L11 owns the absolute-
+ *   positioned render.
+ *
+ *   CCEP parity-lock corpus unaffected: no body-level `<w:framePr>`
+ *   exists in the 6-doc lock (`EnvelopeAddress` style carries a
+ *   framePr in `EU & Global Consultancy Services Agreement` but is
+ *   never referenced by a paragraph). Change is a forward-looking
+ *   correctness fix for the cross-layer chain now that L01→L02→L03→L04
+ *   all emit/honor framePr end-to-end. Cache envelopes from v54
+ *   invalidate because any future document with a real body framePr
+ *   paginates differently.
+ */
+export const LAYOUT_ENGINE_VERSION = 55 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

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

@@ -77,6 +77,7 @@ import {
   resolveCharsPerLine,
   resolveNumberingPrefixLength,
   resolveTextWidth,
+  type LayoutThemeFonts,
 } from "./resolved-formatting-state.ts";
 import { analyzeInvalidation as analyzeInvalidationFn } from "./layout-invalidation.ts";
 import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
@@ -220,6 +221,17 @@ export function buildPageStackWithSplits(
   measurementProvider?: LayoutMeasurementProvider,
 ): PageStackResultWithSplits {
   const defaultTabInterval = document.subParts?.settings?.defaultTabStop ?? 720;
+  // Theme-font fallback for L04 dominant-font resolution. Threaded into
+  // `paginateSectionBlocksWithSplits` so paragraphs whose L03 cascade
+  // carries only a theme slot (e.g. `asciiTheme: "minorHAnsi"`) — common
+  // in CCEP templates with Tahoma/Calibri-bound bodies — route through
+  // the resolved theme family before falling to the DEFAULT factor.
+  const themeFonts: LayoutThemeFonts | undefined = document.subParts?.resolvedTheme
+    ? {
+        minorFont: document.subParts.resolvedTheme.minorFont,
+        majorFont: document.subParts.resolvedTheme.majorFont,
+      }
+    : undefined;
   const pages: DocumentPageSnapshot[] = [];
   const splitsByBlock = new Map<string, ParagraphLineSlice[]>();
   // P8.1b — aggregate note allocations and fragments across all sections,
@@ -339,6 +351,7 @@ export function buildPageStackWithSplits(
       cache,
       defaultTabInterval,
       nextColumnSeed,
+      themeFonts,
     );
     const paginated = paginatedResult.pages;
 
@@ -869,6 +882,56 @@ interface MeasurementCache {
   setLineCount(block: SurfaceBlockSnapshot, columnWidth: number, lineCount: number): void;
 }
 
+/**
+ * Compute contextual-spacing pair mask over a section's blocks.
+ *
+ * OOXML `w:contextualSpacing` rule (§17.3.1.9): when true on a paragraph and
+ * its immediate sibling, AND both share the same paragraph style, the
+ * inter-paragraph spacing (`w:before` on the second, `w:after` on the first)
+ * collapses to zero. Word computes this pair-wise at layout time.
+ *
+ * Inputs considered:
+ *   - `block.contextualSpacing` (direct paragraph attribute)
+ *   - `block.resolvedParagraphFormatting?.contextualSpacing` (L03 style cascade)
+ *
+ * CCEP templates set `w:contextualSpacing` on body styles (styles.xml) rather
+ * than on individual paragraphs (document.xml); the cascade fallback is the
+ * primary lookup there.
+ *
+ * Returns parallel boolean arrays: `before[i]` = suppress `spacingBefore`,
+ * `after[i]` = suppress `spacingAfter`. Non-paragraph blocks are always
+ * `false` on both sides.
+ */
+function computeContextualSpacingAdjustments(
+  blocks: readonly SurfaceBlockSnapshot[],
+): { before: boolean[]; after: boolean[] } {
+  const before = new Array<boolean>(blocks.length).fill(false);
+  const after = new Array<boolean>(blocks.length).fill(false);
+  const hasCs = (b: SurfaceBlockSnapshot | undefined): boolean => {
+    if (!b || b.kind !== "paragraph") return false;
+    return Boolean(
+      b.contextualSpacing ?? b.resolvedParagraphFormatting?.contextualSpacing,
+    );
+  };
+  const styleKey = (b: SurfaceBlockSnapshot): string =>
+    (b.kind === "paragraph" ? b.styleId : undefined) ?? "__default__";
+  for (let i = 0; i < blocks.length; i += 1) {
+    const block = blocks[i];
+    if (!block || block.kind !== "paragraph") continue;
+    if (!hasCs(block)) continue;
+    const key = styleKey(block);
+    const prev = blocks[i - 1];
+    if (prev && prev.kind === "paragraph" && hasCs(prev) && styleKey(prev) === key) {
+      before[i] = true;
+    }
+    const next = blocks[i + 1];
+    if (next && next.kind === "paragraph" && hasCs(next) && styleKey(next) === key) {
+      after[i] = true;
+    }
+  }
+  return { before, after };
+}
+
 function createMeasurementCache(): MeasurementCache {
   const heightByBlock = new WeakMap<SurfaceBlockSnapshot, Map<number, number>>();
   const lineCountByBlock = new WeakMap<SurfaceBlockSnapshot, Map<number, number>>();
@@ -915,6 +978,7 @@ function measureBlockHeight(
   measurementProvider?: LayoutMeasurementProvider,
   cache?: MeasurementCache,
   defaultTabInterval = 720,
+  themeFonts?: LayoutThemeFonts,
 ): number {
   if (!block) return 0;
 
@@ -924,7 +988,12 @@ function measureBlockHeight(
   const compute = (): number => {
     switch (block.kind) {
       case "paragraph": {
-        const formatting = resolveBlockFormatting(block, defaultTabInterval);
+        // §1.19.d — out-of-flow framed paragraphs (ECMA-376 §17.3.1.11)
+        // contribute 0 to inline flow height; L11 owns the positioned render.
+        if (isOutOfFlowFrame(block.frameProperties)) {
+          return 0;
+        }
+        const formatting = resolveBlockFormatting(block, defaultTabInterval, themeFonts);
         if (formatting) {
           // Provider path: sum per-line heights so canvas-backed measurements
           // that emit variable line heights (mixed inline font sizes, etc.)
@@ -963,6 +1032,7 @@ function measureBlockHeight(
           measurementProvider,
           cache,
           defaultTabInterval,
+          themeFonts,
         );
       case "sdt_block":
         return Math.max(
@@ -976,6 +1046,7 @@ function measureBlockHeight(
                 measurementProvider,
                 cache,
                 defaultTabInterval,
+                themeFonts,
               ),
             0,
           ),
@@ -1008,6 +1079,7 @@ function measureTableHeight(
   measurementProvider?: LayoutMeasurementProvider,
   cache?: MeasurementCache,
   defaultTabInterval = 720,
+  themeFonts?: LayoutThemeFonts,
 ): number {
   const TABLE_ROW_PADDING_TWIPS = 120;
   let totalHeight = 0;
@@ -1054,6 +1126,7 @@ function measureTableHeight(
           measurementProvider,
           cache,
           defaultTabInterval,
+          themeFonts,
         );
       }
       contentHeight = Math.max(contentHeight, cellContentHeight + TABLE_ROW_PADDING_TWIPS);
@@ -1100,6 +1173,17 @@ export function __resolveCellWidth(
   return resolveCellWidth(gridColumns, startColumn, columnSpan, fallbackColumnWidth, gridScale);
 }
 
+/**
+ * Exposed for coord §1.19.d framePr unit tests; not part of the
+ * stable surface.
+ */
+export function __test_measureBlockHeight(
+  block: SurfaceBlockSnapshot | undefined,
+  columnWidth: number,
+): number {
+  return measureBlockHeight(block, columnWidth);
+}
+
 function resolveCellWidth(
   gridColumns: readonly number[],
   startColumn: number,
@@ -1327,6 +1411,14 @@ export function paginateSectionBlocksWithSplits(
    * `[0, maxColumns-1]` defensively.
    */
   startColumnIndex = 0,
+  /**
+   * Theme-font fallback. When an L03-resolved segment carries a theme
+   * slot (`asciiTheme: "minorHAnsi"`) but no literal family, the
+   * dominant-font resolver routes through these before falling to the
+   * `DEFAULT_FONT_AVG_CHAR_WIDTH` factor. Source: the document's
+   * `subParts.resolvedTheme` — threaded from `buildPageStackWithSplits`.
+   */
+  themeFonts?: LayoutThemeFonts,
 ): SectionPaginationResult {
   if (blocks.length === 0) {
     return {
@@ -1389,6 +1481,27 @@ export function paginateSectionBlocksWithSplits(
   // table is fully placed.
   const tableProgress = new Map<string, number>();
 
+  // Contextual-spacing pair mask — precomputed once so the inner pagination
+  // loop can fold suppression in O(1) per block without re-scanning neighbors.
+  const contextualSpacing = computeContextualSpacingAdjustments(blocks);
+  const applyContextualSpacingAdjustment = (
+    baseHeight: number,
+    block: SurfaceBlockSnapshot | undefined,
+    index: number,
+  ): number => {
+    if (!block || block.kind !== "paragraph") return baseHeight;
+    if (!contextualSpacing.before[index] && !contextualSpacing.after[index]) {
+      return baseHeight;
+    }
+    const formatting = resolveBlockFormatting(block, defaultTabInterval, themeFonts);
+    if (!formatting) return baseHeight;
+    let delta = 0;
+    if (contextualSpacing.before[index]) delta += formatting.spacingBefore;
+    if (contextualSpacing.after[index]) delta += formatting.spacingAfter;
+    if (delta === 0) return baseHeight;
+    return Math.max(MIN_BLOCK_HEIGHT_TWIPS, baseHeight - delta);
+  };
+
   // P8.1b — per-page note tracking.
   // `pendingNoteKeys` parallels `reservedNotes` but is only snapshotted on
   // page-push (finalization), NOT on column break.
@@ -1510,31 +1623,42 @@ export function paginateSectionBlocksWithSplits(
       const columnWidth =
         columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
         getUsableColumnWidth(layout);
-      const baseHeight = measureBlockHeight(
+      const rawBaseHeight = measureBlockHeight(
         block,
         columnWidth,
         measurementProvider,
         cache,
         defaultTabInterval,
+        themeFonts,
+      );
+      const baseHeight = applyContextualSpacingAdjustment(
+        rawBaseHeight,
+        block,
+        index,
       );
 
       // keepNext: this paragraph must stay with the next one on the same page
       const keepWithNextHeight =
         block.kind === "paragraph" && block.keepNext
           ? baseHeight +
-            measureBlockHeight(
+            applyContextualSpacingAdjustment(
+              measureBlockHeight(
+                blocks[index + 1],
+                columnWidth,
+                measurementProvider,
+                cache,
+                defaultTabInterval,
+                themeFonts,
+              ),
               blocks[index + 1],
-              columnWidth,
-              measurementProvider,
-              cache,
-              defaultTabInterval,
+              index + 1,
             )
           : 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, defaultTabInterval)
+        ? resolveBlockFormatting(block, defaultTabInterval, themeFonts)
         : null;
       const keepLinesActive = formatting?.keepLines ?? false;
 
@@ -1760,6 +1884,16 @@ export function paginateSectionBlocksWithSplits(
         }
       });
 
+      if (hasPageBreak(block)) {
+        // coord-04 §1.18.5 / coord-03 §11 — `<w:br w:type="page"/>`
+        // forces subsequent content onto a new page regardless of
+        // current column position. Mirrors the hasColumnBreak
+        // last-column branch (pushPage + break) so pushPage's note-
+        // allocation snapshot runs.
+        pushPage(nextBoundary);
+        break;
+      }
+
       if (hasColumnBreak(block)) {
         if (columnIndex < maxColumns - 1) {
           // Column break within a multi-column layout: advance to next column.
@@ -1936,6 +2070,37 @@ function currentPageNoteIds(
   return notes;
 }
 
+/**
+ * OOXML §17.3.1.11 — `<w:framePr>`.
+ *
+ * A paragraph carrying frame properties is rendered as a text frame:
+ * it is positioned relative to the page/margin/text (per `hAnchor` /
+ * `vAnchor` / `xAlign` / `yAlign` / `xTwips` / `yTwips`) and the main
+ * text flow wraps around it (per `wrap`). Consequently the framed
+ * paragraph's height MUST NOT contribute to inline block-height
+ * accounting on the page — otherwise the paginator double-counts the
+ * frame (once as inline block, once as the positioned render).
+ *
+ * The exception is `dropCap` (`drop` / `margin`): the frame wraps
+ * only the initial letter; the rest of the paragraph remains in the
+ * main flow, so the paragraph must continue to contribute its
+ * (non-dropped) height. `dropCap="none"` or absent is a full-frame.
+ *
+ * L11 owns the absolute-positioned render; L04 only needs to keep
+ * the frame out of the flow accounting.
+ */
+function isOutOfFlowFrame(
+  frameProperties:
+    | Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["frameProperties"]
+    | undefined,
+): boolean {
+  if (!frameProperties) return false;
+  if (frameProperties.dropCap === "drop" || frameProperties.dropCap === "margin") {
+    return false;
+  }
+  return true;
+}
+
 function hasColumnBreak(block: SurfaceBlockSnapshot): boolean {
   return block.kind === "paragraph" && block.segments.some(
     (segment) =>
@@ -1943,3 +2108,11 @@ function hasColumnBreak(block: SurfaceBlockSnapshot): boolean {
       segment.label === "Column break",
   );
 }
+
+function hasPageBreak(block: SurfaceBlockSnapshot): boolean {
+  return block.kind === "paragraph" && block.segments.some(
+    (segment) =>
+      segment.kind === "opaque_inline" &&
+      segment.label === "Page break",
+  );
+}