postext 0.3.15 → 0.3.17

package/dist/pipeline/build.js

@@ -1,5 +1,5 @@
 import { dimensionToPx } from '../units';
-import { createVDTDocument, createVDTBlock, } from '../vdt';
+import { createVDTDocument, createVDTBlock, createBoundingBox, } from '../vdt';
 import { parseMarkdownMemo } from '../parse';
 import { buildPageLabels, computeHeadingNumbers, } from '../numbering';
 import { extractFrontmatter } from '../frontmatter';
@@ -7,12 +7,16 @@ import { initHyphenator } from '../measure';
 import { resolveAllConfig, computeBaselineGrid } from './config';
 import { resolveBodyStyle, resolveBlockquoteStyle } from './styles';
 import { computeLevelIndentsPx, computeOrderedLevelIndentsPx, computeOrderedListRunMetrics, } from './lists';
-import { resetLinePositions, createPageWithColumns, currentColumn, advanceToNextColumn, advanceToNextPageBoundary, enforcePageParity, placeBlockInColumn, } from './placement';
+import { resetLinePositions, createPageWithColumns, currentColumn, advanceToNextColumn, advanceToNextPageBoundary, enforcePageParity, placeBlockInColumn, placeResourceBlock, } from './placement';
 import { chooseParagraphSplit } from './orphanWidow';
 import { applyStyleAttrs, computeMeasureViewport, computePageMetrics, enrichMathSpans, rollbackTrailingBlocks, stampSourceRanges, } from './buildHelpers';
 import { resolveBlockKind } from './buildBlockKind';
 import { runMeasurement } from './buildMeasurement';
-import { buildHeadersAndFooters } from './headerFooter';
+import { resolveRefSpans, layoutResourceBlock } from './resourceLayout';
+import { computeFloatPlan, floatedResourceIds, } from './floatPlacement';
+import { computeHeadingContext, computeResourceNumbering, } from './resourceNumbering';
+import { defaultResourceTypes } from '../defaults/resourceTypes';
+import { buildHeadersAndFooters, measureHeadingAdvancedDesignHeight } from './headerFooter';
 export class BuildCancelledError extends Error {
     constructor() {
         super('Build cancelled');
@@ -46,12 +50,209 @@ export function buildDocument(content, config, cache, options) {
         }
     }
     const headingPrefixes = computeHeadingNumbers(contentBlocks, headingTemplates);
+    // Resource numbering — computed up front (before the placement loop) so that
+    // captions and inline `:ref`s can resolve their rendered number strings
+    // before measurement. Numbering follows order of first reference in the
+    // document.
+    const resourceTypes = config?.resourceTypes ?? defaultResourceTypes();
+    const resources = content.resources ?? [];
+    const headingContext = computeHeadingContext(contentBlocks);
+    const resourceNumbering = computeResourceNumbering(contentBlocks, resourceTypes, resources, headingContext);
+    // Lookups threaded into block-kind resolution + measurement.
+    const resourceById = new Map();
+    for (const r of resources)
+        resourceById.set(r.id, r);
+    const resourceTypeById = new Map();
+    for (const t of resourceTypes)
+        resourceTypeById.set(t.id, t);
+    const resourceNumberById = new Map();
+    for (const [id, entry] of Object.entries(resourceNumbering)) {
+        resourceNumberById.set(id, entry.number);
+    }
     // Resolve styles
     const bodyStyle = resolveBodyStyle(resolved);
     const blockquoteStyle = resolveBlockquoteStyle(resolved);
     const listLevelIndentsPx = computeLevelIndentsPx(resolved, bodyStyle.fontSizePx);
     const orderedMetrics = computeOrderedListRunMetrics(contentBlocks, resolved, bodyStyle.fontSizePx);
     const orderedLevelIndentsPx = computeOrderedLevelIndentsPx(resolved, bodyStyle.fontSizePx, orderedMetrics.maxWidthByDepth);
+    // --- Float planning (issue #49 — resources float to page bands) ----------
+    // A resource is incorporated by its first reference (an inline `:ref` or a
+    // `::resource` directive, whichever comes first in reading order). Floated
+    // resources detach from the running text and reserve a band at the top or
+    // bottom of the next page opened after that reference; the text flows past
+    // the reference uninterrupted. `position: 'here'` resources keep inline
+    // `::resource` placement and are not floated.
+    const floatPlan = computeFloatPlan(contentBlocks, resources, resourceTypes);
+    const floatedIds = floatedResourceIds(floatPlan);
+    const floatsByFirstBlock = new Map();
+    for (const f of floatPlan) {
+        const list = floatsByFirstBlock.get(f.firstBlockIdx);
+        if (list)
+            list.push(f);
+        else
+            floatsByFirstBlock.set(f.firstBlockIdx, [f]);
+    }
+    // Floats whose first reference has been passed but which are not yet placed
+    // into a page band, in reading order.
+    const pendingFloats = [];
+    const floatGapPx = bodyStyle.lineHeightPx;
+    const minTextPx = bodyStyle.lineHeightPx * 3;
+    /** Offset a resolved resource block's caption/table geometry from
+     *  block-relative to absolute page coordinates (mirrors inline placement). */
+    const offsetResourceBlockToAbsolute = (rb, ox, oy) => {
+        for (const ln of rb.captionLines) {
+            ln.bbox.x += ox;
+            ln.bbox.y += oy;
+            ln.baseline += oy;
+        }
+        if (rb.table) {
+            for (const cell of rb.table.cells) {
+                cell.rect.x += ox;
+                cell.rect.y += oy;
+                for (const cl of cell.lines) {
+                    cl.bbox.x += ox;
+                    cl.bbox.y += oy;
+                    cl.baseline += oy;
+                }
+            }
+        }
+    };
+    /** Measure + build a float block at horizontal offset `x` (y = 0), or null
+     *  when the resource id is unknown. Caller offsets it to its final `y`. */
+    const buildFloatBlock = (resourceId, x, width) => {
+        const resource = resourceById.get(resourceId);
+        if (!resource)
+            return null;
+        const { block: rb, totalHeight } = layoutResourceBlock({
+            resource,
+            resourceType: resourceTypeById.get(resource.typeId),
+            number: resourceNumberById.get(resourceId) ?? '',
+            resolved,
+            columnWidth: width,
+            resourceNumbering,
+            resourceTypes,
+            resources,
+        });
+        const blk = createVDTBlock(`float-${resourceId}`, 'resource', bodyStyle.fontString, bodyStyle.color, bodyStyle.textAlign);
+        blk.resourceBlock = rb;
+        blk.dirty = false;
+        blk.snappedToGrid = false;
+        blk.bbox = createBoundingBox(x, 0, width, totalHeight);
+        blk.lines = [];
+        offsetResourceBlockToAbsolute(rb, x, 0);
+        return { block: blk, height: totalHeight };
+    };
+    /** Reserve top/bottom bands on a freshly opened page and position as many
+     *  pending floats as fit, shrinking the affected columns so body text flows
+     *  around them. Preserves reading order: stops at the first float that does
+     *  not fit (so figures never reorder relative to their references), except
+     *  on a band that is still all-text, where a dominating/oversized float is
+     *  force-placed so the queue always makes progress. */
+    const flushFloatsIntoPage = (page) => {
+        if (pendingFloats.length === 0)
+            return;
+        const topUsed = page.columns.map(() => 0);
+        const botUsed = page.columns.map(() => 0);
+        const floats = page.floats ?? [];
+        /** Try to place one float on this page. Returns whether it was placed,
+         *  must be deferred (does not fit), or skipped (unknown id). Only mutates
+         *  page geometry when it actually places. */
+        const attemptFloat = (f) => {
+            const pageSpan = f.span === 'page' && page.columns.length > 1;
+            let targetCols;
+            if (pageSpan) {
+                targetCols = page.columns.map((_, i) => i);
+            }
+            else {
+                // Single-column float: pick the column with the most room left.
+                let best = 0;
+                for (let i = 1; i < page.columns.length; i++) {
+                    if (topUsed[i] + botUsed[i] < topUsed[best] + botUsed[best])
+                        best = i;
+                }
+                targetCols = [best];
+            }
+            const firstCol = page.columns[targetCols[0]];
+            const width = pageSpan ? contentArea.width : firstCol.bbox.width;
+            const xLeft = pageSpan ? contentArea.x : firstCol.bbox.x;
+            const built = buildFloatBlock(f.resourceId, xLeft, width);
+            if (!built)
+                return 'skip';
+            const need = built.height + floatGapPx;
+            let minAvail = Infinity;
+            let anyReserved = false;
+            for (const c of targetCols) {
+                minAvail = Math.min(minAvail, page.columns[c].availableHeight);
+                if (topUsed[c] > 0 || botUsed[c] > 0)
+                    anyReserved = true;
+            }
+            // Keep some text room, unless this band is still all-text (then a
+            // dominating / oversized float is force-placed so the queue progresses).
+            if (need > minAvail - minTextPx && anyReserved)
+                return 'defer';
+            let y = 0;
+            for (const c of targetCols) {
+                const col = page.columns[c];
+                if (f.position === 'top') {
+                    y = col.bbox.y; // float sits at the current top edge
+                    col.bbox.y += need; // push column content below the band
+                    col.bbox.height = Math.max(0, col.bbox.height - need);
+                    topUsed[c] += need;
+                }
+                else {
+                    col.bbox.height = Math.max(0, col.bbox.height - need);
+                    y = col.bbox.y + col.bbox.height + floatGapPx; // flush toward the bottom
+                    botUsed[c] += need;
+                }
+                col.availableHeight = Math.max(0, col.availableHeight - need);
+            }
+            offsetResourceBlockToAbsolute(built.block.resourceBlock, 0, y);
+            built.block.bbox = createBoundingBox(xLeft, y, width, built.height);
+            built.block.pageIndex = page.index;
+            built.block.columnIndex = targetCols[0];
+            floats.push(built.block);
+            return 'placed';
+        };
+        // Full-width (page-span) floats reserve the outermost bands first, so a
+        // later single-column float nests inside the remaining column space rather
+        // than overlapping a full-width band. Within each pass, stop at the first
+        // float that does not fit to preserve reading order.
+        for (const pageSpanPass of [true, false]) {
+            let i = 0;
+            while (i < pendingFloats.length) {
+                const f = pendingFloats[i];
+                const isPageSpan = f.span === 'page' && page.columns.length > 1;
+                if (isPageSpan !== pageSpanPass) {
+                    i++;
+                    continue;
+                }
+                const r = attemptFloat(f);
+                if (r === 'placed' || r === 'skip')
+                    pendingFloats.splice(i, 1);
+                else
+                    break; // defer: leave this and the rest of the pass for a later page
+            }
+        }
+        if (floats.length > 0)
+            page.floats = floats;
+    };
+    /** Drain floats still pending after body placement (referenced on the last
+     *  page, or never followed by a content-overflow page break) onto freshly
+     *  appended pages. Each new page force-places at least one float. */
+    const finalizeFloats = () => {
+        let guard = 0;
+        while (pendingFloats.length > 0 && guard++ < 1000) {
+            const before = pendingFloats.length;
+            const page = createPageWithColumns(doc.pages.length, resolved, contentArea, pageWidthPx, pageHeightPx);
+            doc.pages.push(page);
+            flushFloatsIntoPage(page);
+            if (pendingFloats.length === before)
+                break; // safety: no progress
+        }
+    };
+    /** Reserve floats on each freshly opened content page. Passed only to the
+     *  content-flow column advances — parity / force-blank pages never get it. */
+    const onNewPage = (page) => flushFloatsIntoPage(page);
     // Placement cursor
     const cursor = { pageIndex: 0, columnIndex: 0 };
     let blockIdCounter = 0;
@@ -93,6 +294,13 @@ export function buildDocument(content, config, cache, options) {
         if (options?.shouldCancel?.())
             throw new BuildCancelledError();
         const rawBlock = contentBlocks[blockIdx];
+        // Enqueue floats first-referenced in this block so the next page opened
+        // while placing it (or any later block) reserves their band. Done before
+        // placement so a reference near a column/page boundary still floats onto
+        // the page that follows it.
+        const floatsHere = floatsByFirstBlock.get(blockIdx);
+        if (floatsHere)
+            pendingFloats.push(...floatsHere);
         // --- Directives ----------------------------------------------------
         if (rawBlock.type === 'directive') {
             const name = rawBlock.directiveName;
@@ -136,6 +344,16 @@ export function buildDocument(content, config, cache, options) {
                 }
                 flushPendingNumberingAtBoundary();
             }
+            // `span: 'page'` headings open a chapter band across the full content
+            // width. Always start on a fresh page boundary so the band sits at the
+            // page top, and reset the cursor to column 0 so all other columns will
+            // have their availableHeight reduced symmetrically after placement.
+            if (level?.span === 'page') {
+                pendingSpacing = 0;
+                advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                cursor.columnIndex = 0;
+                flushPendingNumberingAtBoundary();
+            }
         }
         const id = `block-${blockIdCounter++}`;
         const kind = resolveBlockKind(rawBlock, {
@@ -147,24 +365,140 @@ export function buildDocument(content, config, cache, options) {
             listLevelIndentsPx,
             orderedLevelIndentsPx,
             orderedMetrics,
+            resourceById,
+            resourceTypeById,
+            resourceNumberById,
         });
         const { style, vdtType, headingLevel, numberPrefix, listBullet, listDepth, listKind, bulletXOffsetInColumn, strikethroughText } = kind;
         let contentBlock = kind.contentBlock;
+        // --- Resource blocks (image / svg / table + caption) -----------------
+        // Measured and placed atomically (kept-together) — no mid-content split
+        // for v1. An unknown resource id produces no output (warnings handle it).
+        if (vdtType === 'resource') {
+            if (!kind.resource) {
+                flushPendingNumberingAtBoundary();
+                continue;
+            }
+            // Floated resources are not placed inline at their `::resource`
+            // directive — the directive is just an anchor (already enqueued above);
+            // the float lands in a page band. Only `position: 'here'` resources fall
+            // through to inline placement.
+            if (floatedIds.has(kind.resource.id)) {
+                flushPendingNumberingAtBoundary();
+                continue;
+            }
+            const rCol = currentColumn(doc, cursor);
+            const { resourceBlock, measured } = runMeasurement({
+                vdtType,
+                rawBlock,
+                contentBlock,
+                style,
+                measureMaxWidth: rCol.bbox.width,
+                measureOptions: { textAlign: style.textAlign },
+                mathEnabled: resolved.math.enabled,
+                useRich: false,
+                resolved,
+                resources,
+                resourceTypes,
+                resourceNumbering,
+                resource: kind.resource,
+                resourceType: kind.resourceType,
+                resourceNumber: kind.resourceNumber,
+            });
+            if (!resourceBlock) {
+                flushPendingNumberingAtBoundary();
+                continue;
+            }
+            const groupHeight = measured.totalHeight;
+            const blk = createVDTBlock(id, 'resource', style.fontString, style.color, style.textAlign);
+            blk.resourceBlock = resourceBlock;
+            blk.dirty = false;
+            blk.snappedToGrid = false;
+            blk.sourceStart = rawBlock.sourceStart + bodyOffset;
+            blk.sourceEnd = rawBlock.sourceEnd + bodyOffset;
+            // The single placeholder line carries the group height; caption lines are
+            // carried on `resourceBlock` and offset to absolute coords below.
+            blk.lines = [{
+                    text: '',
+                    bbox: { x: 0, y: 0, width: resourceBlock.bodyRect.width, height: groupHeight },
+                    baseline: 0,
+                    hyphenated: false,
+                    segments: [],
+                    isLastLine: true,
+                }];
+            const spacingBefore = pendingSpacing;
+            placeResourceBlock(blk, groupHeight, spacingBefore, cursor, doc, resolved, contentArea, pageWidthPx, pageHeightPx);
+            // `placeBlockInColumn` (inside placeResourceBlock) shifts `blk.lines`; the
+            // resource's own caption/table lines live on `resourceBlock` and must be
+            // offset to absolute page coordinates here using the placed bbox origin.
+            const ox = blk.bbox.x;
+            const oy = blk.bbox.y;
+            for (const ln of resourceBlock.captionLines) {
+                ln.bbox.x += ox;
+                ln.bbox.y += oy;
+                ln.baseline += oy;
+            }
+            if (resourceBlock.table) {
+                for (const cell of resourceBlock.table.cells) {
+                    cell.rect.x += ox;
+                    cell.rect.y += oy;
+                    for (const cl of cell.lines) {
+                        cl.bbox.x += ox;
+                        cl.bbox.y += oy;
+                        cl.baseline += oy;
+                    }
+                }
+            }
+            doc.blocks.push(blk);
+            pendingSpacing = style.marginBottomPx;
+            flushPendingNumberingAtBoundary();
+            continue;
+        }
         // Measure text — use rich measurement for blocks with bold spans
         const col = currentColumn(doc, cursor);
         // Resolve inline math on spans (no-op when the block has no math).
         const mathEnabled = resolved.math.enabled;
         contentBlock = enrichMathSpans(contentBlock, style, resolved);
-        const hasRichSpans = contentBlock.spans.some((s) => s.bold || s.italic || s.mathRender);
+        // Resolve inline `:ref{…}` spans to their computed label so references
+        // print their number in the running text. Each label becomes one atomic,
+        // non-breaking token tagged with its `refResourceId` (handled by the
+        // rich-text measurer), so we always take the rich path for ref blocks.
+        if (contentBlock.spans.some((s) => s.ref)) {
+            contentBlock = {
+                ...contentBlock,
+                spans: resolveRefSpans(contentBlock.spans, resourceNumbering, resourceTypes, resources, {
+                    bold: bodyStyle.referenceBold ?? true,
+                    italic: bodyStyle.referenceItalic ?? false,
+                }),
+            };
+        }
+        const hasRichSpans = contentBlock.spans.some((s) => s.bold || s.italic || s.mathRender || s.ref);
         // List items reserve horizontal space for indent + bullet + gap.
         const { measureMaxWidth, lineXShift, measureFirstLineIndent, measureHangingIndent, } = computeMeasureViewport(col.bbox.width, style, listBullet);
+        // First-paragraph-after-heading: typographic convention used in many
+        // scientific publications and book styles where the paragraph that
+        // immediately follows a heading is rendered without first-line indent.
+        // Only applies to regular paragraphs without hanging indent; list items
+        // and hanging-indent paragraphs are unaffected.
+        let effectiveFirstLineIndent = measureFirstLineIndent;
+        if (vdtType === 'paragraph'
+            && !resolved.bodyText.indentAfterHeading
+            && !resolved.bodyText.hangingIndent
+            && blockIdx > 0) {
+            let prevIdx = blockIdx - 1;
+            while (prevIdx >= 0 && contentBlocks[prevIdx].type === 'directive')
+                prevIdx--;
+            if (prevIdx >= 0 && contentBlocks[prevIdx].type === 'heading') {
+                effectiveFirstLineIndent = 0;
+            }
+        }
         const runtActive = resolved.bodyText.avoidRunts
             && (vdtType === 'paragraph'
                 || (vdtType === 'listItem' && resolved.bodyText.avoidRuntsInLists));
         const measureOptions = {
             textAlign: style.textAlign,
             hyphenate: style.hyphenate,
-            firstLineIndentPx: measureFirstLineIndent,
+            firstLineIndentPx: effectiveFirstLineIndent,
             hangingIndent: measureHangingIndent,
             optimal: resolved.bodyText.optimalLineBreaking,
             maxStretchRatio: resolved.bodyText.maxWordSpacing,
@@ -264,6 +598,27 @@ export function buildDocument(content, config, cache, options) {
             const totalRemainHeight = vdtType === 'mathDisplay'
                 ? (remainingLines[0]?.bbox.height ?? style.lineHeightPx)
                 : remainingLines.length * style.lineHeightPx;
+            // For headings with an enabled advanced-design slot, the rendered
+            // overlay may extend below the natural text bottom. Measure the slot's
+            // actual content bottom so the reserved block height (and the
+            // subsequent marginBottom + grid snap) starts from there.
+            let effectiveRemainHeight = totalRemainHeight;
+            if (vdtType === 'heading' && headingLevel !== undefined && partIndex === 0) {
+                const lvl = resolved.headings.levels.find((l) => l.level === headingLevel);
+                if (lvl) {
+                    const full = remainingLines
+                        .map((ln) => (ln.segments ?? []).map((s) => s.text).join(''))
+                        .join(' ');
+                    const pref = numberPrefix ?? '';
+                    const title = pref && full.startsWith(`${pref} `) ? full.slice(pref.length + 1) : full;
+                    // Span-page openers lay out across the full content area (both
+                    // columns); in-column headings use just the column width.
+                    const measureWidth = lvl.span === 'page' ? contentArea.width : curCol.bbox.width;
+                    const designBottom = measureHeadingAdvancedDesignHeight(lvl, { titleText: title, formattedNumber: pref, chapterNumber: pref }, measureWidth, resolved.page.dpi, doc.metadata, cursor.pageIndex);
+                    if (designBottom > effectiveRemainHeight)
+                        effectiveRemainHeight = designBottom;
+                }
+            }
             // Keep-with-list: if this colon-paragraph would fit but would leave no
             // room for the first list item, split off the colon line (or push the
             // whole paragraph when it is a single line or the split would leave a
@@ -309,7 +664,7 @@ export function buildDocument(content, config, cache, options) {
                         remainingLines = remainingLines.slice(splitAt);
                         partIndex++;
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         continue;
                     }
                     // Can't cleanly split the colon line off — would create a widow.
@@ -339,19 +694,19 @@ export function buildDocument(content, config, cache, options) {
                         }
                         blockIdx -= headingRunCount + 1;
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         break;
                     }
                     if (headingRunCount === 0) {
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         continue;
                     }
                     // headingRunCount === curCol.blocks.length: fall through to place.
                 }
             }
             // Block fits in current column
-            if (totalRemainHeight <= effectiveAvailable) {
+            if (effectiveRemainHeight <= effectiveAvailable) {
                 // Heading keep-with-next: never leave a heading as the last block of a
                 // column. If the following (non-heading) block wouldn't have room to
                 // place at least its widow-minimum number of lines after this heading,
@@ -368,7 +723,7 @@ export function buildDocument(content, config, cache, options) {
                     && nextBlock !== null
                     && curCol.blocks.length > 0) {
                     const wouldUsedHeight = (curCol.bbox.height - curCol.availableHeight) + spacingBefore;
-                    const naturalBottom = wouldUsedHeight + totalRemainHeight + style.marginBottomPx;
+                    const naturalBottom = wouldUsedHeight + effectiveRemainHeight + style.marginBottomPx;
                     const snappedBottom = shouldSnapToGrid
                         ? Math.ceil((naturalBottom - 0.01) / baselineGrid) * baselineGrid
                         : naturalBottom;
@@ -386,11 +741,11 @@ export function buildDocument(content, config, cache, options) {
                             // rolled-back heading.
                             blockIdx -= rollbackCount + 1;
                             pendingSpacing = 0;
-                            advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                            advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                             break;
                         }
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         continue;
                     }
                 }
@@ -428,7 +783,7 @@ export function buildDocument(content, config, cache, options) {
                 }
                 blk.sourceMap = absoluteSourceMap;
                 blk.plainPrefixLen = prefixLen;
-                let h = totalRemainHeight;
+                let h = effectiveRemainHeight;
                 if (shouldSnapToGrid && partIndex === 0) {
                     // Snap using the absolute position in the column so that the block
                     // bottom lands on a baseline grid line. This accounts for off-grid
@@ -436,7 +791,7 @@ export function buildDocument(content, config, cache, options) {
                     // the minimum marginBottom — the grid always wins, but the margin
                     // below is guaranteed to be at least marginBottomPx.
                     const usedHeight = curCol.bbox.height - curCol.availableHeight;
-                    const naturalBottom = usedHeight + totalRemainHeight + style.marginBottomPx;
+                    const naturalBottom = usedHeight + effectiveRemainHeight + style.marginBottomPx;
                     // Tolerance guards against FP drift: if naturalBottom is already on
                     // the grid (e.g. marginBottom is an exact multiple of baselineGrid),
                     // don't round up to the next line.
@@ -446,6 +801,20 @@ export function buildDocument(content, config, cache, options) {
                 placeBlockInColumn(blk, h, curCol, cursor);
                 finalizeListItem(blk, partIndex === 0);
                 doc.blocks.push(blk);
+                // Page-spanning heading: reserve the same vertical band in every
+                // other column on this page so body text under the opener band
+                // starts below it in ALL columns, not just the one it was placed in.
+                if (vdtType === 'heading' && headingLevel !== undefined) {
+                    const lvl = resolved.headings.levels.find((l) => l.level === headingLevel);
+                    if (lvl?.span === 'page') {
+                        const page = doc.pages[cursor.pageIndex];
+                        for (const otherCol of page.columns) {
+                            if (otherCol !== curCol) {
+                                otherCol.availableHeight = Math.max(0, otherCol.availableHeight - h);
+                            }
+                        }
+                    }
+                }
                 // For snapped headings/list-tails the margin is baked into the snap;
                 // for unsnapped ones (consecutive) track it for collapsing
                 if (vdtType === 'listItem' && nextIsListItem) {
@@ -502,7 +871,7 @@ export function buildDocument(content, config, cache, options) {
                     remainingLines = remainingLines.slice(choice.splitAt);
                     partIndex++;
                     pendingSpacing = 0;
-                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                     continue;
                 }
                 // choice.splitAt === 0: fall through to push whole paragraph to next column
@@ -518,12 +887,12 @@ export function buildDocument(content, config, cache, options) {
                     if (rollbackCount > 0) {
                         blockIdx -= rollbackCount + 1;
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         break;
                     }
                 }
                 pendingSpacing = 0;
-                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                 continue;
             }
             // Empty column but block still doesn't fit (block taller than page) — place anyway
@@ -554,6 +923,9 @@ export function buildDocument(content, config, cache, options) {
         }
         flushPendingNumberingAtBoundary();
     }
+    // Place any floats still pending (referenced on the last page, or never
+    // followed by a content-overflow page break) onto freshly appended pages.
+    finalizeFloats();
     // Stamp page-number info onto every page (including blank parity pages).
     const labels = buildPageLabels(doc.pages.length, pageNumberSegments);
     for (let i = 0; i < doc.pages.length; i++) {