postext 0.3.16 → 0.3.18

package/dist/pipeline/build.js

@@ -1,26 +1,47 @@
 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';
 import { initHyphenator } from '../measure';
-import { resolveAllConfig, computeBaselineGrid } from './config';
+import { resolveAllConfig, computeBaselineGrid, buildHeadingLevelMap } 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';
+import { totalGapLines, proposeBalanceLines, MAX_BALANCING_PASSES } from './columnBalancing';
 export class BuildCancelledError extends Error {
     constructor() {
         super('Build cancelled');
         this.name = 'BuildCancelledError';
     }
 }
-export function buildDocument(content, config, cache, options) {
+/** Page-number formats accepted by the `::numbering` directive. */
+const ALLOWED_PAGE_FORMATS = new Set([
+    'decimal',
+    'lower-roman',
+    'upper-roman',
+    'lower-alpha',
+    'upper-alpha',
+]);
+/**
+ * Single placement pass. `balanceExtraPx` carries the column-balancing
+ * adjustments (extra top spacing per heading, keyed by content-block index);
+ * `forcedBreakPages` reports the pages whose break into the next page was
+ * explicit (`:::pagebreak`, heading `breakBefore`, chapter opener) rather
+ * than natural content overflow — those pages keep their short last column.
+ */
+function buildDocumentPass(content, config, cache, options, balanceExtraPx) {
     const resolved = resolveAllConfig(config);
+    const headingLevelByNumber = buildHeadingLevelMap(resolved);
     const dpi = resolved.page.dpi;
     // Initialize hyphenator if needed
     if (resolved.bodyText.hyphenation.enabled && resolved.bodyText.textAlign === 'justify') {
@@ -46,16 +67,266 @@ 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';
+            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;
+            }
+            // Both band kinds are corrected against the baseline grid so the text
+            // around them — and the facing page — stays on the global rhythm:
+            //  - top: the band pushes the column start (`col.bbox.y`) downward, and
+            //    all grid snapping inside the column is anchored at that start. The
+            //    band height is rounded up to a grid multiple (growing the gap
+            //    below the float) or every line in the displaced column would land
+            //    off-grid, visibly misaligned with neighbouring columns.
+            //  - bottom: the float is anchored so its visual bottom sits on the
+            //    grid — the caption's last line shares its baseline with the last
+            //    text line of the other columns (captionless content aligns its
+            //    bottom edge to the last grid slot). Pages then end at the same
+            //    height across columns and across facing pages.
+            let need;
+            let floatY = 0;
+            if (f.position === 'top') {
+                const rawNeed = built.height + floatGapPx;
+                need = Math.ceil((rawNeed - 0.01) / baselineGrid) * baselineGrid;
+            }
+            else {
+                const bottomLimit = Math.min(...targetCols.map((c) => {
+                    const cb = page.columns[c].bbox;
+                    return cb.y + cb.height;
+                }));
+                const gridAlignedBottom = contentArea.y
+                    + Math.floor((bottomLimit - contentArea.y + 0.01) / baselineGrid) * baselineGrid;
+                const capLines = built.block.resourceBlock.captionLines;
+                if (capLines.length > 0) {
+                    // Body baselines sit at 0.2 × grid above each slot bottom; anchor
+                    // the caption's last baseline there.
+                    const lastBaseline = capLines[capLines.length - 1].baseline; // block-relative
+                    floatY = gridAlignedBottom - 0.2 * baselineGrid - lastBaseline;
+                }
+                else {
+                    floatY = gridAlignedBottom - built.height;
+                }
+                need = 0;
+                for (const c of targetCols) {
+                    const col = page.columns[c];
+                    need = Math.max(need, col.bbox.height - (floatY - floatGapPx - col.bbox.y));
+                }
+            }
+            // 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);
+                    col.availableHeight = Math.max(0, col.availableHeight - need);
+                    topUsed[c] += need;
+                }
+                else {
+                    y = floatY;
+                    const newHeight = Math.max(0, floatY - floatGapPx - col.bbox.y);
+                    const reserved = col.bbox.height - newHeight;
+                    col.bbox.height = newHeight;
+                    col.availableHeight = Math.max(0, col.availableHeight - reserved);
+                    botUsed[c] += reserved;
+                }
+            }
+            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;
     let pendingSpacing = 0;
+    // Pages whose break into the next page is explicit rather than natural
+    // overflow. Column balancing leaves their last column short (a chapter's
+    // closing page legitimately ends early).
+    const forcedBreakPages = new Set();
+    const markForcedBreak = () => {
+        const curPage = doc.pages[cursor.pageIndex];
+        if (curPage.columns.some((c) => c.blocks.length > 0)) {
+            forcedBreakPages.add(cursor.pageIndex);
+        }
+    };
     // Page-numbering segments. The implicit first segment comes from
     // `cfg.page.pageNumbering`; `:::numbering` directives append more,
     // each applied at the next page boundary.
@@ -82,23 +353,24 @@ export function buildDocument(content, config, cache, options) {
             lastSeenPageIndex = cursor.pageIndex;
         }
     };
-    const ALLOWED_PAGE_FORMATS = new Set([
-        'decimal',
-        'lower-roman',
-        'upper-roman',
-        'lower-alpha',
-        'upper-alpha',
-    ]);
     for (let blockIdx = 0; blockIdx < contentBlocks.length; blockIdx++) {
         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;
             const attrs = rawBlock.directiveAttrs ?? {};
             if (name === 'pagebreak') {
                 pendingSpacing = 0;
+                markForcedBreak();
                 advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
                 const parity = attrs.parity;
                 if (parity === 'odd'
@@ -126,16 +398,28 @@ export function buildDocument(content, config, cache, options) {
         }
         // --- Heading `breakBefore` ----------------------------------------
         if (rawBlock.type === 'heading' && rawBlock.level) {
-            const level = resolved.headings.levels.find((l) => l.level === rawBlock.level);
+            const level = headingLevelByNumber.get(rawBlock.level);
             const bb = level?.breakBefore;
             if (bb && bb.enabled) {
                 pendingSpacing = 0;
+                markForcedBreak();
                 advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
                 if (bb.parity !== 'any') {
                     enforcePageParity(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, bb.parity);
                 }
                 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;
+                markForcedBreak();
+                advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                cursor.columnIndex = 0;
+                flushPendingNumberingAtBoundary();
+            }
         }
         const id = `block-${blockIdCounter++}`;
         const kind = resolveBlockKind(rawBlock, {
@@ -147,24 +431,135 @@ 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.contentIndex = blockIdx;
+            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.
+            offsetResourceBlockToAbsolute(resourceBlock, blk.bbox.x, blk.bbox.y);
+            doc.blocks.push(blk);
+            // Snap the flow position after the resource to the baseline grid (the
+            // group height is arbitrary), baking in at least marginBottom — same
+            // convention as snapped headings — so the following text lands back on
+            // the global grid instead of inheriting the resource's offset.
+            {
+                const rCol = currentColumn(doc, cursor);
+                const usedHeight = rCol.bbox.height - rCol.availableHeight;
+                const naturalBottom = usedHeight + style.marginBottomPx;
+                const snappedBottom = Math.ceil((naturalBottom - 0.01) / baselineGrid) * baselineGrid;
+                rCol.availableHeight = Math.max(0, rCol.bbox.height - snappedBottom);
+            }
+            pendingSpacing = 0;
+            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,
@@ -249,6 +644,17 @@ export function buildDocument(content, config, cache, options) {
                 spacingBefore = pendingSpacing;
                 if (vdtType === 'heading' || vdtType === 'mathDisplay') {
                     spacingBefore = Math.max(spacingBefore, style.marginTopPx);
+                    // Column balancing: extra whole grid lines above this heading so
+                    // the column it sits in ends flush with the page bottom. Applied
+                    // after margin collapsing — the heading's effective top margin
+                    // grows by the assigned lines. Suppressed for first-in-column
+                    // headings (no top margin there), keeping columns starting at the
+                    // page top.
+                    if (vdtType === 'heading') {
+                        const extraPx = balanceExtraPx?.get(blockIdx);
+                        if (extraPx)
+                            spacingBefore += extraPx;
+                    }
                 }
                 else if (vdtType === 'listItem') {
                     const prevWasList = blockIdx > 0 && contentBlocks[blockIdx - 1].type === 'listItem';
@@ -264,6 +670,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 = headingLevelByNumber.get(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
@@ -294,6 +721,7 @@ export function buildDocument(content, config, cache, options) {
                         const splitLines = remainingLines.slice(0, splitAt);
                         const blk = createVDTBlock(id, vdtType, style.fontString, style.color, style.textAlign);
                         applyStyleAttrs(blk, style);
+                        blk.contentIndex = blockIdx;
                         blk.headingLevel = headingLevel;
                         if (numberPrefix)
                             blk.numberPrefix = numberPrefix;
@@ -309,7 +737,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 +767,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 +796,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 +814,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;
                     }
                 }
@@ -401,6 +829,7 @@ export function buildDocument(content, config, cache, options) {
                 const partId = partIndex === 0 ? id : `${id}-cont-${partIndex}`;
                 const blk = createVDTBlock(partId, vdtType, style.fontString, style.color, style.textAlign);
                 applyStyleAttrs(blk, style);
+                blk.contentIndex = blockIdx;
                 if (partIndex === 0) {
                     blk.headingLevel = headingLevel;
                     if (numberPrefix)
@@ -428,7 +857,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 +865,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 +875,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 = headingLevelByNumber.get(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) {
@@ -481,6 +924,7 @@ export function buildDocument(content, config, cache, options) {
                     const splitLines = remainingLines.slice(0, choice.splitAt);
                     const blk = createVDTBlock(partId, vdtType, style.fontString, style.color, style.textAlign);
                     applyStyleAttrs(blk, style);
+                    blk.contentIndex = blockIdx;
                     if (partIndex === 0) {
                         blk.headingLevel = headingLevel;
                         if (numberPrefix)
@@ -502,7 +946,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,18 +962,19 @@ 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
             const partId = partIndex === 0 ? id : `${id}-cont-${partIndex}`;
             const blk = createVDTBlock(partId, vdtType, style.fontString, style.color, style.textAlign);
             applyStyleAttrs(blk, style);
+            blk.contentIndex = blockIdx;
             if (partIndex === 0)
                 blk.headingLevel = headingLevel;
             blk.lines = resetLinePositions(remainingLines, style.lineHeightPx);
@@ -554,6 +999,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++) {
@@ -568,6 +1016,51 @@ export function buildDocument(content, config, cache, options) {
     buildHeadersAndFooters(doc);
     doc.converged = true;
     doc.iterationCount = 1;
-    return doc;
+    return { doc, forcedBreakPages };
+}
+export function buildDocument(content, config, cache, options) {
+    let best = buildDocumentPass(content, config, cache, options);
+    // --- Column balancing (vertical justification) ------------------------
+    // Iteratively re-place the document with extra grid lines above headings
+    // until every balanceable column ends flush with the page bottom (or no
+    // further adjustment is possible). Each retry recomputes the remaining
+    // gaps on the freshly placed document, so split/keep-with-next decisions
+    // that shift under the new spacing are accounted for. The best layout
+    // (fewest leftover gap lines) always wins — a retry that regresses is
+    // discarded.
+    const balancing = best.doc.config.headings.balancing;
+    if (!balancing.enabled)
+        return best.doc;
+    let bestScore = totalGapLines(best.doc, best.forcedBreakPages);
+    let appliedLines = new Map();
+    let passCount = 1;
+    let converged = bestScore === 0;
+    while (!converged && passCount < MAX_BALANCING_PASSES) {
+        const proposal = proposeBalanceLines(best.doc, best.forcedBreakPages, appliedLines, balancing.maxLinesPerHeading);
+        if (!proposal.changed) {
+            // No heading can absorb the remaining gaps — stable.
+            converged = true;
+            break;
+        }
+        const extraPx = new Map();
+        for (const [idx, n] of proposal.lines)
+            extraPx.set(idx, n * best.doc.baselineGrid);
+        const next = buildDocumentPass(content, config, cache, options, extraPx);
+        passCount++;
+        const score = totalGapLines(next.doc, next.forcedBreakPages);
+        if (score < bestScore) {
+            best = next;
+            bestScore = score;
+            appliedLines = proposal.lines;
+            converged = score === 0;
+        }
+        else {
+            // Plateau or regression — keep the best layout found so far.
+            break;
+        }
+    }
+    best.doc.iterationCount = passCount;
+    best.doc.converged = converged || bestScore === 0;
+    return best.doc;
 }
 //# sourceMappingURL=build.js.map