postext 0.3.28 → 0.3.30

package/dist/pipeline/build.js

@@ -16,13 +16,13 @@ import { measureContentBlock } from './measureContentBlock';
 import { planParagraphContainers } from './paragraphContainers';
 import { planParts, derivePartMeasureContext } from './parts';
 import { layoutCallout, offsetCalloutToAbsolute, pickCalloutStyle, planCallouts, resolveCalloutAttrs, } from './calloutLayout';
-import { layoutResourceBlock } from './resourceLayout';
+import { layoutResourceBlock, planTableSlice } from './resourceLayout';
 import { computeFloatPlan, floatedResourceIds, } from './floatPlacement';
 import { enumerateCurrentPageSlots, measureFloatBand, columnHasFloatBand, fitsStrict, trueBottom, } from './floatSlots';
 import { computeHeadingContext, computeResourceNumbering, } from './resourceNumbering';
 import { defaultResourceTypes } from '../defaults/resourceTypes';
 import { buildHeadersAndFooters, measureHeadingAdvancedDesignHeight } from './headerFooter';
-import { totalGapLines, proposeBalanceLines, MAX_BALANCING_PASSES } from './columnBalancing';
+import { totalGapLines, proposeBalanceLines, collectColumnGaps, firstDivergentColumn, MAX_BALANCING_PASSES, balanceKey } from './columnBalancing';
 import { applyBandCap, uncapBand, columnBottom, bandCapLines, bandTop, resolveBandCaps, resolveTrailingCaps, bandCapLinesAroundZone, } from './bandCaps';
 import { raggedUrlLines } from './raggedUrl';
 export class BuildCancelledError extends Error {
@@ -207,6 +207,8 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     };
     const floatGapPx = bodyStyle.lineHeightPx;
     const minTextPx = bodyStyle.lineHeightPx * 3;
+    /** Fewest body rows the closing slice of a split table carries. */
+    const MIN_TAIL_ROWS = 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) => {
@@ -220,6 +222,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             ln.bbox.y += oy;
             ln.baseline += oy;
         }
+        for (const ln of rb.continuesLines) {
+            ln.bbox.x += ox;
+            ln.bbox.y += oy;
+            ln.baseline += oy;
+        }
         if (rb.captionBar) {
             rb.captionBar.rect.x += ox;
             rb.captionBar.rect.y += oy;
@@ -228,6 +235,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             for (const cell of rb.table.cells) {
                 cell.rect.x += ox;
                 cell.rect.y += oy;
+                if (cell.image) {
+                    cell.image.rect.x += ox;
+                    cell.image.rect.y += oy;
+                }
                 for (const cl of cell.lines) {
                     cl.bbox.x += ox;
                     cl.bbox.y += oy;
@@ -236,7 +247,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             }
         }
     };
-    const layoutFloat = (resourceId, width) => {
+    const layoutFloat = (resourceId, width, slice) => {
         const resource = resourceById.get(resourceId);
         if (!resource)
             return null;
@@ -249,17 +260,38 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             resourceNumbering,
             resourceTypes,
             resources,
+            ...(slice ? { slice } : {}),
         });
     };
+    /** Row count of a table resource (0 for anything else). */
+    const tableRowCount = (resourceId) => resourceById.get(resourceId)?.table?.model.rows.length ?? 0;
+    /** The slice a pending float stands for: the whole resource, or — for the
+     *  rest of a split table — its remaining rows, laid out as the closing
+     *  slice (no marker; the note). */
+    const sliceOf = (f) => f.startRow !== undefined && f.startRow > 0
+        ? { startRow: f.startRow, endRow: tableRowCount(f.resourceId), continues: false }
+        : undefined;
+    const sliceKey = (slice) => slice ? `:${slice.startRow}-${slice.endRow}${slice.continues ? '+' : ''}` : '';
+    /** Row metrics of a table float laid out in full at a width, memoised. */
+    const tableMetricsMemo = new Map();
+    const tableMetrics = (resourceId, width) => {
+        const key = `${resourceId}:${width.toFixed(2)}`;
+        const memo = tableMetricsMemo.get(key);
+        if (memo !== undefined)
+            return memo;
+        const m = layoutFloat(resourceId, width)?.tableRows ?? null;
+        tableMetricsMemo.set(key, m);
+        return m;
+    };
     /** Height (and caption baseline) of a float at a given width, memoised —
      *  fit checks run for every pending float on every loop iteration. */
     const floatMeasureMemo = new Map();
-    const measureFloat = (resourceId, width) => {
-        const key = `${resourceId}:${width.toFixed(2)}`;
+    const measureFloat = (resourceId, width, slice) => {
+        const key = `${resourceId}:${width.toFixed(2)}${sliceKey(slice)}`;
         const memo = floatMeasureMemo.get(key);
         if (memo !== undefined)
             return memo;
-        const laid = layoutFloat(resourceId, width);
+        const laid = layoutFloat(resourceId, width, slice);
         let m = null;
         if (laid) {
             // A bottom band aligns the float's LAST text line to the grid: the
@@ -269,7 +301,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             const rb = laid.block;
             const bodyBottom = rb.bodyRect.y + rb.bodyRect.height;
             let lastBaseline;
-            for (const ln of [...rb.captionLines, ...rb.noteLines]) {
+            for (const ln of [...rb.captionLines, ...rb.noteLines, ...rb.continuesLines]) {
                 if (ln.bbox.y < bodyBottom - 0.5)
                     continue;
                 if (lastBaseline === undefined || ln.baseline > lastBaseline)
@@ -285,12 +317,13 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     };
     /** 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 laid = layoutFloat(resourceId, width);
+    const buildFloatBlock = (resourceId, x, width, slice) => {
+        const laid = layoutFloat(resourceId, width, slice);
         if (!laid)
             return null;
         const { block: rb, totalHeight } = laid;
-        const blk = createVDTBlock(`float-${resourceId}`, 'resource', bodyStyle.fontString, bodyStyle.color, bodyStyle.textAlign);
+        const id = slice && slice.startRow > 0 ? `float-${resourceId}-cont-${slice.startRow}` : `float-${resourceId}`;
+        const blk = createVDTBlock(id, 'resource', bodyStyle.fontString, bodyStyle.color, bodyStyle.textAlign);
         blk.resourceBlock = rb;
         blk.dirty = false;
         blk.snappedToGrid = false;
@@ -303,6 +336,9 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
      *  sends single-column floats to the least reserved column). */
     const floatReserved = new Map();
     const reservedOf = (col) => floatReserved.get(col) ?? { top: 0, bottom: 0 };
+    /** Content index of the block that first referenced the latest float
+     *  reserved at the head of each column. */
+    const topFloatRefOf = new Map();
     /** Kind of cap the column is under (`undefined` when uncapped). A cap that
      *  cannot be attributed to the active band is treated as a span cap — the
      *  conservative reading, which keeps the column's bottom off the slot list. */
@@ -314,24 +350,136 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         }
         return 'span';
     };
+    /** Floats (or slices) placed so far — the progress signal of the drain
+     *  loop, which a split does not shorten the queue for. */
+    let floatsPlaced = 0;
+    /**
+     * The slice of a table float that fits a fresh band of `avail` px, when
+     * the whole (rest of the) table does not: the leading rows within the
+     * band, cut where `planTableSlice` allows, verified against the band
+     * geometry and shrunk row by row until it fits. `tableStyle.overflow`
+     * decides what becomes of the rows left over — a rest float to continue
+     * on the next page (`'split'`), nothing (`'clip'`) — or, for `'hide'`,
+     * that the table is dropped. Returns null for a figure or a table with
+     * nothing to cut, which are force-placed like before.
+     */
+    const splitTableFloat = (f, width, position, targetCols, contentArea, avail) => {
+        const rowCount = tableRowCount(f.resourceId);
+        if (rowCount === 0)
+            return null;
+        const overflow = resolved.tableStyle.overflow;
+        if (overflow === 'hide')
+            return 'skip';
+        const metrics = tableMetrics(f.resourceId, width);
+        if (!metrics)
+            return null;
+        const startRow = f.startRow ?? 0;
+        const firstBody = startRow > 0 ? Math.max(startRow, metrics.headerRowCount) : metrics.headerRowCount;
+        if (firstBody >= rowCount)
+            return null;
+        // Overhead of a continuing slice at this width — caption, gaps, marker —
+        // from a one-row probe; the row heights come from the metrics.
+        const probe = layoutFloat(f.resourceId, width, { startRow, endRow: firstBody + 1, continues: true });
+        if (!probe)
+            return null;
+        const overhead = probe.totalHeight - probe.block.bodyRect.height;
+        // A top band rounds up to the grid: the tallest float it holds within
+        // `avail` is the grid multiple below it, less the gap.
+        const hMax = Math.floor((avail + 0.01) / baselineGrid) * baselineGrid - floatGapPx;
+        let end = planTableSlice(metrics, startRow, hMax - overhead);
+        // Nothing fits: carry the smallest slice anyway (it overflows, as a
+        // dominating figure would) rather than stall the queue.
+        const floor = firstBody + 1;
+        if (end < floor)
+            end = floor;
+        // A last page holding a row or two under a repeated header reads as a
+        // stranded tail: give the closing slice at least `MIN_TAIL_ROWS` rows by
+        // handing some back from this one (at a breakable edge, not under a
+        // group head), when this slice can spare them.
+        const tail = rowCount - end;
+        if (overflow === 'split' && tail > 0 && tail < MIN_TAIL_ROWS) {
+            let e = rowCount - MIN_TAIL_ROWS;
+            while (e > floor && (!(metrics.breakableAfter[e - 1] ?? true) || metrics.groupHeaderRow[e - 1]))
+                e--;
+            if (e >= floor && e >= end - MIN_TAIL_ROWS)
+                end = e;
+        }
+        const fits = (slice) => {
+            const measure = measureFloat(f.resourceId, width, slice);
+            if (!measure)
+                return true;
+            const { need } = measureFloatBand(position, measure, targetCols, contentArea, baselineGrid, floatGapPx, (c) => trueBottom(c, uncappedBottoms));
+            return need <= avail + 0.01;
+        };
+        const sliceFor = (e) => ({
+            startRow,
+            endRow: e,
+            continues: e < rowCount && overflow === 'split',
+        });
+        let slice = sliceFor(end);
+        // The caption may wrap differently with its suffix, the closing slice
+        // carries the note instead of the marker: verify, backing off a row at
+        // a time (over breakable edges) when the band still overflows.
+        for (let guard = 0; guard < 8 && end > floor && !fits(slice); guard++) {
+            do
+                end--;
+            while (end > floor && !(metrics.breakableAfter[end - 1] ?? true));
+            slice = sliceFor(end);
+        }
+        const rest = slice.continues ? { ...f, startRow: end } : undefined;
+        return rest ? { slice, rest } : { slice };
+    };
     /**
      * Reserve a float band on `targetCols` (one column, or every text column
      * of the band for a page-span float) and position the float there.
      * `'fresh'` is the freshly-opened-page rule: keep three lines of text room
      * once a band already holds a float, but force-place a dominating float
-     * on an all-text band so the queue always progresses. `'strict'` is the
-     * current-page rule: the band must fit in each column's remaining height
-     * (below its content), keeping the text room only next to another band.
-     * Only mutates page geometry when it places.
+     * on an all-text band so the queue always progresses — a table is cut to
+     * the band instead and continues on the next page (see
+     * {@link splitTableFloat}). `'strict'` is the current-page rule: the band
+     * must fit in each column's remaining height (below its content), keeping
+     * the text room only next to another band. Only mutates page geometry
+     * when it places.
      */
-    const placeFloatInColumns = (page, f, targetCols, position, pageSpan, mode) => {
+    /** The band a float would take in a slot — its height (`need`) and the
+     *  float's `y` — without reserving it. `null` when the float cannot be
+     *  measured. */
+    const probeFloatBand = (page, f, targetCols, position, pageSpan, anchorToCap) => {
         const first = targetCols[0];
         const width = pageSpan ? page.contentArea.width : first.bbox.width;
         const xLeft = pageSpan ? page.contentArea.x : first.bbox.x;
-        const measure = measureFloat(f.resourceId, width);
+        const slice = sliceOf(f);
+        const measure = measureFloat(f.resourceId, width, slice);
         if (!measure)
+            return null;
+        // A bottom band normally anchors to the column's true foot (under a
+        // trailing cap, the page bottom — the closing-page figure). Before a
+        // page-span box the cap IS the band's foot: the figure hugs the text
+        // and the box follows both.
+        const bottomOf = (c) => anchorToCap ? c.bbox.y + c.bbox.height : trueBottom(c, uncappedBottoms);
+        const { need, y } = measureFloatBand(position, measure, targetCols, page.contentArea, baselineGrid, floatGapPx, bottomOf);
+        return { need, y, measure, slice, width, xLeft };
+    };
+    /** Free height `col` keeps for the flow once a float band `probe` is
+     *  reserved in it at `position` (mirrors the reservation arithmetic of
+     *  `placeFloatInColumns`; a capped column absorbs a bottom band in its
+     *  remembered true bottom, so its free height does not change). */
+    const availableAfterBand = (col, position, probe, anchorToCap) => {
+        if (position === 'top')
+            return Math.max(0, col.availableHeight - probe.need);
+        if (uncappedBottoms.has(col) && !anchorToCap)
+            return col.availableHeight;
+        const newHeight = Math.max(0, probe.y - floatGapPx - col.bbox.y);
+        return Math.max(0, col.availableHeight - (col.bbox.height - newHeight));
+    };
+    const placeFloatInColumns = (page, f, targetCols, position, pageSpan, mode, anchorToCap = false) => {
+        const first = targetCols[0];
+        const probe = probeFloatBand(page, f, targetCols, position, pageSpan, anchorToCap);
+        if (!probe)
             return 'skip';
-        const { need, y } = measureFloatBand(position, measure, targetCols, page.contentArea, baselineGrid, floatGapPx, (c) => trueBottom(c, uncappedBottoms));
+        const { width, xLeft } = probe;
+        let { slice, measure, need, y } = probe;
+        let rest;
         if (mode === 'fresh') {
             let minAvail = Infinity;
             let anyReserved = false;
@@ -343,10 +491,25 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             }
             if (need > minAvail - minTextPx && anyReserved)
                 return 'defer';
+            if (need > minAvail + 0.01) {
+                // Dominating the band: a table is cut to it.
+                const split = splitTableFloat(f, width, position, targetCols, page.contentArea, minAvail);
+                if (split === 'skip')
+                    return 'skip';
+                if (split) {
+                    slice = split.slice;
+                    rest = split.rest;
+                    const m = measureFloat(f.resourceId, width, slice);
+                    if (!m)
+                        return 'skip';
+                    measure = m;
+                    ({ need, y } = measureFloatBand(position, measure, targetCols, page.contentArea, baselineGrid, floatGapPx, (c) => trueBottom(c, uncappedBottoms)));
+                }
+            }
         }
         else {
             for (const c of targetCols) {
-                if (position === 'bottom' && uncappedBottoms.has(c)) {
+                if (position === 'bottom' && uncappedBottoms.has(c) && !anchorToCap) {
                     // Trailing cap: the band must lie entirely below the level cut.
                     if (y - floatGapPx < c.bbox.y + c.bbox.height - 0.01)
                         return 'defer';
@@ -356,7 +519,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     return 'defer';
             }
         }
-        const built = buildFloatBlock(f.resourceId, xLeft, width);
+        const built = buildFloatBlock(f.resourceId, xLeft, width, slice);
         if (!built)
             return 'skip';
         for (const col of targetCols) {
@@ -366,10 +529,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 col.bbox.height = Math.max(0, col.bbox.height - need);
                 col.availableHeight = Math.max(0, col.availableHeight - need);
                 r.top += need;
+                topFloatRefOf.set(col, Math.max(topFloatRefOf.get(col) ?? -1, f.firstBlockIdx));
             }
             else {
                 const capped = uncappedBottoms.get(col);
-                if (capped !== undefined) {
+                if (capped !== undefined && !anchorToCap) {
                     uncappedBottoms.set(col, capped - need);
                 }
                 else {
@@ -377,6 +541,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     const reserved = col.bbox.height - newHeight;
                     col.bbox.height = newHeight;
                     col.availableHeight = Math.max(0, col.availableHeight - reserved);
+                    // Anchored to a cap: the band is the column's content down to
+                    // the cut; the true bottom shrinks by it too, so a span box
+                    // measuring its room never cuts across the figure.
+                    if (capped !== undefined)
+                        uncappedBottoms.set(col, capped - need);
                 }
                 r.bottom += need;
             }
@@ -387,7 +556,21 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         built.block.pageIndex = page.index;
         built.block.columnIndex = first.index;
         (page.floats ??= []).push(built.block);
-        return 'placed';
+        floatsPlaced++;
+        return rest ? { rest } : 'placed';
+    };
+    /** Apply a slot outcome to the queue at `i`: drop a placed float, keep a
+     *  deferred one, swap in the rest of a split table. Returns the index to
+     *  continue from. */
+    const settle = (i, r) => {
+        if (r === 'defer')
+            return i + 1;
+        if (typeof r === 'object') {
+            pendingFloats[i] = r.rest;
+            return i + 1;
+        }
+        pendingFloats.splice(i, 1);
+        return i;
     };
     const positionsFor = (f) => f.position === 'auto' ? ['top', 'bottom'] : [f.position];
     /** Reserve top/bottom bands on a freshly opened page and position as many
@@ -429,38 +612,123 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     if (r !== 'defer')
                         break;
                 }
-                if (r === 'defer')
-                    i++;
-                else
-                    pendingFloats.splice(i, 1);
+                i = settle(i, r);
             }
         }
     };
+    /** The keep-together box content block `idx` opens, when it is one that
+     *  lays out inline in a column of the current band (`span: 'column'`,
+     *  placement `here`): its height at a column width, so the floats placed
+     *  right before it can tell whether a slot would starve it. */
+    const keepTogetherBoxAt = (idx) => {
+        const b = contentBlocks[idx];
+        if (!b || b.type !== 'containerStart' || b.containerName !== 'callout')
+            return null;
+        const plan = calloutPlan.get(idx);
+        const style = plan ? pickCalloutStyle(resolved.calloutStyles, plan.attrs.type) : undefined;
+        if (!plan || !style || !style.keepTogether)
+            return null;
+        const { span, placement } = resolveCalloutAttrs(style, plan.attrs);
+        if (placement !== 'here')
+            return null;
+        const page = doc.pages[cursor.pageIndex];
+        if (span === 'page' && bandColumns(page, currentBand(page, cursor)).length > 1)
+            return null;
+        const L = makeCalloutLayouter(idx, plan, style);
+        const heights = new Map();
+        return {
+            heightAt: (width) => {
+                const key = Math.round(width * 100);
+                let h = heights.get(key);
+                if (h === undefined) {
+                    const r = L.layoutRange(CUT_START, L.end, width, 'probe', false);
+                    h = r.totalHeight + Math.max(pendingSpacing, r.marginTopPx);
+                    heights.set(key, h);
+                }
+                return h;
+            },
+        };
+    };
+    /** Whether reserving float `f` in `slot` would leave the keep-together
+     *  box that comes next with no column of the current band to land in —
+     *  when, without the float, one of them (the cursor's, or an empty one
+     *  after it) still holds it. A float yields to such a box, as a
+     *  compositor would: the box stays in flow and the figure takes the next
+     *  slot (usually the next page) instead of pushing the box off the page
+     *  and leaving the column with the figure alone. */
+    const slotStarvesBox = (page, f, slot, box, anchorToCap) => {
+        const cursorCol = page.columns[cursor.columnIndex];
+        if (!cursorCol)
+            return false;
+        const candidates = bandColumns(page, currentBand(page, cursor))
+            .filter((c) => c.kind !== 'span' && c.index >= cursorCol.index && (c === cursorCol || c.blocks.length === 0));
+        const fitsIn = (c, available) => available >= box.heightAt(c.bbox.width) - 0.01;
+        if (!candidates.some((c) => fitsIn(c, c.availableHeight)))
+            return false;
+        const probe = probeFloatBand(page, f, slot.cols, slot.position, slot.pageSpan, anchorToCap);
+        if (!probe)
+            return false;
+        const after = (c) => slot.cols.includes(c) ? availableAfterBand(c, slot.position, probe, anchorToCap) : c.availableHeight;
+        return !candidates.some((c) => fitsIn(c, after(c)));
+    };
     /** Offer every pending float the free slots of the current page after the
      *  cursor (bottom of the referencing column, top / bottom of the next
      *  empty columns; the band bottom for page-span floats). Runs before each
-     *  block is placed, so a float lands in the first gap after its reference. */
-    const tryPlacePendingFloatsOnCurrentPage = () => {
+     *  block is placed, so a float lands in the first gap after its reference.
+     *  `nextBlockIdx` is that block: a keep-together box it opens holds the
+     *  slots that would starve it (see `slotStarvesBox`). */
+    const tryPlacePendingFloatsOnCurrentPage = (preferTop = false, nextBlockIdx) => {
         if (pendingFloats.length === 0)
             return;
         const page = doc.pages[cursor.pageIndex];
+        const box = nextBlockIdx !== undefined ? keepTogetherBoxAt(nextBlockIdx) : null;
         for (let i = 0; i < pendingFloats.length;) {
             const f = pendingFloats[i];
             let r = 'defer';
-            for (const slot of enumerateCurrentPageSlots(page, cursor.columnIndex, f, capKindOf)) {
-                r = placeFloatInColumns(page, f, slot.cols, slot.position, slot.pageSpan, 'strict');
+            let slots = enumerateCurrentPageSlots(page, cursor.columnIndex, f, capKindOf);
+            // A page-span box comes next: the head of an empty column keeps the
+            // band cuttable under the float (the box then sits below both the
+            // text and the figure), where the referencing column's foot would
+            // wall the box off the page. A page-span figure waits for the box
+            // itself, which cuts the band under the text and sets the figure
+            // there, above the box (`placeSpanFloatsAtCut`) — its only slot here
+            // would be the band's foot, under the box.
+            if (preferTop && f.span === 'page' && bandColumns(page, currentBand(page, cursor)).length > 1) {
+                i++;
+                continue;
+            }
+            if (preferTop)
+                slots = [...slots.filter((s) => s.position === 'top'), ...slots.filter((s) => s.position !== 'top')];
+            for (const slot of slots) {
+                if (box && slotStarvesBox(page, f, slot, box, preferTop))
+                    continue;
+                r = placeFloatInColumns(page, f, slot.cols, slot.position, slot.pageSpan, 'strict', preferTop);
                 if (r !== 'defer')
                     break;
             }
-            if (r === 'defer')
-                i++;
-            else
-                pendingFloats.splice(i, 1);
+            i = settle(i, r);
         }
     };
     /** 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);
+    /** Whether content block `idx` opens a callout that will span the page
+     *  in the current (multi-column) band — the floats placed right before
+     *  it prefer the head of an empty column. */
+    const spanBoxAt = (idx) => {
+        const b = contentBlocks[idx];
+        if (!b || b.type !== 'containerStart' || b.containerName !== 'callout')
+            return false;
+        const plan = calloutPlan.get(idx);
+        const style = plan ? pickCalloutStyle(resolved.calloutStyles, plan.attrs.type) : undefined;
+        if (!style)
+            return false;
+        const { span, placement } = resolveCalloutAttrs(style, plan.attrs);
+        if (span !== 'page' || placement === 'fixed')
+            return false;
+        const page = doc.pages[cursor.pageIndex];
+        return bandColumns(page, currentBand(page, cursor)).length > 1;
+    };
     /** Chapter barrier: place every pending float before the boundary — in
      *  the current page's free slots, then on fresh pages opened ahead of it
      *  (each force-places at least one float). The cursor is left on the last
@@ -469,12 +737,12 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         tryPlacePendingFloatsOnCurrentPage();
         let guard = 0;
         while (pendingFloats.length > 0 && guard++ < 1000) {
-            const before = pendingFloats.length;
+            const before = floatsPlaced;
             const startPageIndex = cursor.pageIndex;
             do {
                 advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
             } while (cursor.pageIndex === startPageIndex);
-            if (pendingFloats.length === before)
+            if (floatsPlaced === before)
                 break; // safety: no progress
         }
     };
@@ -531,6 +799,19 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     let activeCap = null;
     /** True bottoms of capped columns (restored when the span block cuts). */
     const uncappedBottoms = new Map();
+    /** Column balancing: height (px) the levers added inside each column so
+     *  far — extra grid lines above headings / list ends and lines gained by
+     *  loose paragraphs. Balancing only ever fills a column's bottom gap, so
+     *  a placement rule that needs slack *after* a block (keep-colon-with-
+     *  list) must see the column as it was before the levers filled it:
+     *  otherwise the block that closed the column in the plain pass moves to
+     *  the next column, the flow shifts on every later page, and the pass is
+     *  discarded as a regression. */
+    const balanceExtraInColumn = new Map();
+    const addBalanceExtra = (col, px) => {
+        if (px > 0)
+            balanceExtraInColumn.set(col, (balanceExtraInColumn.get(col) ?? 0) + px);
+    };
     const bandCapProposals = new Map();
     const spanPlacedInBand = new Set();
     const bandCapsApplied = new Set();
@@ -599,11 +880,22 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         const aroundZone = zone ? bandCapLinesAroundZone(cols, baselineGrid, zone, (c) => columnBottom(c, uncappedBottoms)) : null;
         if (aroundZone === null && Math.max(...bottoms) - Math.min(...bottoms) <= baselineGrid + 0.5)
             return;
+        // Float bands reserved at the columns' feet are the band's content too:
+        // the level cut must leave them room under the text (a figure placed
+        // before a span box then anchors to the cut, see `anchorToCap`).
+        const footBands = cols.reduce((sum, c) => sum + reservedOf(c).bottom, 0);
+        // A figure heading an otherwise empty column keeps its slot: the cut
+        // goes no higher than the band it takes, or the capped pass evicts it
+        // to a page of its own.
+        const top = bandTop(cols);
+        const floatHeads = cols
+            .filter((c) => c.blocks.length === 0 && reservedOf(c).top > 0)
+            .map((c) => Math.ceil((c.bbox.y - top - 0.01) / baselineGrid));
         bandCapProposals.set(boundaryIndex, {
             kind: 'trailing',
             startContentIndex: bandStart.contentIndex,
             startPart: bandStart.part,
-            lines: aroundZone ?? bandCapLines(cols, baselineGrid),
+            lines: aroundZone ?? Math.max(bandCapLines(cols, baselineGrid, footBands), ...floatHeads),
             retries: 0,
             ...(aroundZone !== null ? { zone } : {}),
         });
@@ -696,6 +988,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             doc.blocks.push(child);
         }
     };
+    const CUT_START = { child: 0, line: 0 };
     const makeCalloutLayouter = (startIdx, plan, style) => {
         const children = contentBlocks.slice(startIdx + 1, plan.endIdx);
         const realAt = [];
@@ -705,12 +998,15 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         });
         const layoutRange = (from, to, width, frameId, continuation) => {
             let n = 0;
+            // A cut inside child `to.child` includes that child (its first
+            // `to.line` lines); a cut at a child's head excludes it.
+            const toChild = to.line > 0 ? to.child + 1 : to.child;
             return layoutCallout({
                 style,
                 attrs: plan.attrs,
                 continuation,
-                children: children.slice(from, to),
-                childStartIdx: startIdx + 1 + from,
+                children: children.slice(from.child, toChild),
+                childStartIdx: startIdx + 1 + from.child,
                 width,
                 ctx: measureCtx,
                 resolved,
@@ -718,49 +1014,64 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 frameId,
                 nextChildId: () => `${frameId}-c${n++}`,
                 paragraphStyleFor: (idx) => paragraphContainers.byBlock[idx]?.style,
+                ...(from.line > 0 ? { lineFrom: from.line } : {}),
+                ...(to.line > 0 ? { lineTo: to.line } : {}),
             });
         };
-        return { children, childBase: startIdx + 1, realAt, layoutRange };
+        return { children, childBase: startIdx + 1, realAt, end: { child: children.length, line: 0 }, layoutRange };
     };
-    /** The longest leading fragment of the children from `from` on whose box
-     *  is at most `roomPx` tall — at least one child, and at least one left
-     *  for the rest. The full layout's child geometry picks the candidate
-     *  (box bottom = child bottom + the box's tail below its last child);
-     *  the candidate is then laid out for real and shortened while it does
-     *  not fit. `null` when not even the first child fits. */
-    const splitCalloutFragment = (L, from, width, roomPx, frameId, continuation) => {
-        const starts = L.realAt.filter((k) => k >= from);
-        if (starts.length < 2)
-            return null;
-        const full = L.layoutRange(from, L.children.length, width, frameId, continuation);
+    /** The longest leading fragment of the box from cut `from` on whose box
+     *  is at most `roomPx` tall. Cuts fall between children or between the
+     *  lines of a text child, and every fragment keeps at least the style's
+     *  `splitMinLines` lines on its side of the cut (a figure or a display
+     *  formula counts as one line). The full layout's geometry ranks the
+     *  candidates (box bottom = content bottom at the cut + the box's tail
+     *  below its last child); the deepest candidate that fits is laid out
+     *  for real and taken when it truly fits. `null` when none does. */
+    const splitCalloutFragment = (L, from, width, roomPx, frameId, continuation, minLines) => {
+        const full = L.layoutRange(from, L.end, width, frameId, continuation);
         const lastChild = full.children[full.children.length - 1];
         if (!lastChild)
             return null;
         const tail = full.totalHeight - (lastChild.bbox.y + lastChild.bbox.height);
-        /** Frame-relative bottom of the last laid-out child before position `to`. */
-        const bottomBefore = (to) => {
-            let bottom = 0;
-            for (const c of full.children) {
-                if (c.contentIndex !== undefined && c.contentIndex < L.childBase + to) {
-                    bottom = Math.max(bottom, c.bbox.y + c.bbox.height);
+        const totalLines = full.children.reduce((n, c) => n + Math.max(1, c.lines.length), 0);
+        /** Candidate cuts with the head's content bottom and line count. */
+        const candidates = [];
+        let linesBefore = 0;
+        for (let i = 0; i < full.children.length; i++) {
+            const c = full.children[i];
+            const k = (c.contentIndex ?? L.childBase) - L.childBase;
+            const cuttable = c.type !== 'resource' && c.type !== 'mathDisplay' && c.lines.length > 1;
+            // The first laid-out child of a continuation opens after `from.line`
+            // lines: cuts inside it are counted from the child's own head.
+            const lineBase = k === from.child ? from.line : 0;
+            if (cuttable) {
+                for (let l = 1; l < c.lines.length; l++) {
+                    const line = c.lines[l - 1];
+                    candidates.push({ cut: { child: k, line: lineBase + l }, bottom: line.bbox.y + line.bbox.height, headLines: linesBefore + l });
                 }
             }
-            return bottom;
-        };
-        let j = starts.length - 1;
-        while (j >= 1 && bottomBefore(starts[j]) + tail > roomPx + 0.01)
-            j--;
-        for (; j >= 1; j--) {
-            const to = starts[j];
-            const result = L.layoutRange(from, to, width, frameId, continuation);
+            linesBefore += Math.max(1, c.lines.length);
+            if (i < full.children.length - 1) {
+                candidates.push({ cut: { child: k + 1, line: 0 }, bottom: c.bbox.y + c.bbox.height, headLines: linesBefore });
+            }
+        }
+        const min = Math.max(1, minLines);
+        const viable = candidates
+            .filter((c) => c.headLines >= min && totalLines - c.headLines >= min)
+            .sort((a, b) => b.bottom - a.bottom);
+        for (const c of viable) {
+            if (c.bottom + tail > roomPx + 0.01)
+                continue;
+            const result = L.layoutRange(from, c.cut, width, frameId, continuation);
             if (result.totalHeight <= roomPx + 0.01)
-                return { to, result };
+                return { to: c.cut, result };
         }
         return null;
     };
-    /** Absolute content indices of the children in `[from, to)` of `L`, for
-     *  the fragment's source range. */
-    const fragmentRange = (L, from, to) => ({ firstChildIdx: L.childBase + from, lastChildIdx: L.childBase + to - 1 });
+    /** Absolute content indices of the children a fragment from cut `from`
+     *  to cut `to` of `L` touches, for the fragment's source range. */
+    const fragmentRange = (L, from, to) => ({ firstChildIdx: L.childBase + from.child, lastChildIdx: L.childBase + (to.line > 0 ? to.child : to.child - 1) });
     const markFragment = (result, part, continued) => {
         if (result.frame.callout) {
             result.frame.callout.part = part;
@@ -835,9 +1146,92 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             const bottoms = cols.map((c) => c.bbox.y + (c.bbox.height - c.availableHeight));
             return Math.max(...bottoms) - Math.min(...bottoms) <= baselineGrid + 0.5;
         };
-        /** Position in the children the fragment to place starts at, and its
-         *  0-based index among the fragments (0 = the box, or its head). */
-        let from = 0;
+        /** Level for the box: the text columns end level, and a column holding
+         *  only a float band (a figure at its head, no text yet) counts as level
+         *  when a band cap could not level it either — the figure was first
+         *  referenced by the very block before the box, so a cut that spills
+         *  that block into the figure's column leaves the figure no slot after
+         *  its reference (it would fall off the page, and the box with it). The
+         *  box then cuts under the text and the figure alike; a figure
+         *  referenced earlier keeps the cap route, which flows text under it. */
+        const lastBlockBefore = () => {
+            let j = startIdx - 1;
+            while (j >= 0 && isMarkerBlock(contentBlocks[j]))
+                j--;
+            return j;
+        };
+        const levelForBox = (cols) => {
+            if (isBandLevel(cols))
+                return true;
+            const textCols = cols.filter((c) => c.blocks.length > 0);
+            const floatOnly = cols.filter((c) => c.blocks.length === 0 && reservedOf(c).top > 0);
+            if (textCols.length === 0 || textCols.length + floatOnly.length !== cols.length)
+                return false;
+            if (!isBandLevel(textCols))
+                return false;
+            const before = lastBlockBefore();
+            // However tall the figure is: the text before the box is all placed,
+            // so no cut could level the columns any better — the box goes under
+            // both, the slack under the text being the compositor's trade.
+            return floatOnly.every((c) => topFloatRefOf.get(c) === before);
+        };
+        /**
+         * A page-span figure referenced before the box takes the cut first: the
+         * band is closed level under the text, the figure spans the page right
+         * there (where the text ended, as the compositor reads it), and the box
+         * goes on below — or to the next page when it no longer fits. Only when
+         * the band can be cut for the box (level, or capped for it) and the
+         * figure fits between the cut and the band bottom; otherwise the figure
+         * stays pending for the ordinary slots. Returns whether any was set.
+         */
+        const placeSpanFloatsAtCut = (page, capActiveHere) => {
+            let placedAny = false;
+            for (let i = 0; i < pendingFloats.length;) {
+                const f = pendingFloats[i];
+                const cols = bandColumns(page, currentBand(page, cursor));
+                if (f.span !== 'page' || cols.length < 2 || !((capActiveHere && !placedAny) || levelForBox(cols))) {
+                    i++;
+                    continue;
+                }
+                const width = page.contentArea.width;
+                const slice = sliceOf(f);
+                const measure = measureFloat(f.resourceId, width, slice);
+                if (!measure) {
+                    i++;
+                    continue;
+                }
+                const cutY = gridUp(page, bandUsedBottom(cols));
+                const spacing = cols.some((c) => c.blocks.length > 0) ? floatGapPx : 0;
+                const need = needFor(spacing, measure.height, floatGapPx);
+                const bandBottom = Math.min(...cols.map((c) => columnBottom(c, uncappedBottoms)));
+                if (cutY + need > bandBottom + 0.01) {
+                    i++;
+                    continue;
+                }
+                const built = buildFloatBlock(f.resourceId, page.contentArea.x, width, slice);
+                if (!built) {
+                    i++;
+                    continue;
+                }
+                if (capActiveHere && !placedAny) {
+                    uncapBand(cols, uncappedBottoms);
+                    spanPlacedInBand.add(startIdx);
+                }
+                closeBandAndInsertSpan(page, cols, cutY, built.block, need, cursor, spacing, built.height);
+                // The float was built at (x, 0): move its inner geometry down to
+                // where the span column put it.
+                offsetResourceBlockToAbsolute(built.block.resourceBlock, 0, built.block.bbox.y);
+                built.block.contentIndex = f.firstBlockIdx;
+                doc.blocks.push(built.block);
+                floatsPlaced++;
+                placedAny = true;
+                pendingFloats.splice(i, 1);
+            }
+            return placedAny;
+        };
+        /** Cut the fragment to place starts at, and its 0-based index among
+         *  the fragments (0 = the box, or its head). */
+        let from = CUT_START;
         let part = 0;
         let frameId = firstFrameId;
         /** The box already moved to a fresh page (or sits on an empty one):
@@ -846,7 +1240,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         for (;;) {
             let page = doc.pages[cursor.pageIndex];
             const continuation = part > 0;
-            const layoutAt = (width) => L.layoutRange(from, L.children.length, width, frameId, continuation);
+            const layoutAt = (width) => L.layoutRange(from, L.end, width, frameId, continuation);
             const result = layoutAt(page.contentArea.width);
             /** Where the box would cut the current band, and whether it fits (room
              *  is measured against the columns' TRUE bottoms — a capped band keeps
@@ -855,7 +1249,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
              *  `requireLevel` is set. */
             const measureBand = (requireLevel) => {
                 const cols = bandColumns(page, currentBand(page, cursor));
-                if (cols.length === 0 || (requireLevel && !isBandLevel(cols)))
+                if (cols.length === 0 || (requireLevel && !levelForBox(cols)))
                     return null;
                 const cutY = gridUp(page, bandUsedBottom(cols));
                 const bandHasContent = cols.some((c) => c.blocks.length > 0);
@@ -870,11 +1264,70 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             // Is this band capped for this very box? Then it cuts at the band's
             // used bottom (at most the cap) even when the last column is short.
             const cap = part === 0 ? bandCaps?.get(startIdx) : undefined;
-            const capActive = cap !== undefined
+            let capActive = cap !== undefined
                 && activeCap !== null
                 && activeCap.spanIndex === startIdx
                 && activeCap.pageIndex === page.index
                 && activeCap.band === currentBand(page, cursor);
+            // A page-span figure referenced before the box cuts the band first
+            // and the box measures the fresh band under it. A barrier box then
+            // takes every other pending float — the current page's free slots,
+            // else pages opened ahead — before it lands.
+            if (part === 0) {
+                if (placeSpanFloatsAtCut(page, capActive))
+                    capActive = false;
+                if (style.floatBarrier && pendingFloats.length > 0) {
+                    const pageBefore = cursor.pageIndex;
+                    const bandBefore = currentBand(page, cursor);
+                    // An uneven, uncapped band the figures are about to leave behind
+                    // gets the cap that levels it: a span cap when a page-span figure
+                    // would fit under the level cut — the capped pass sets it there
+                    // and the box follows — else a trailing cap, the figure and the
+                    // box moving on and the band ending level like a closing one.
+                    // Only a page-span figure is planned for here; column figures keep
+                    // the ordinary slots (their level is the band cap's own business).
+                    const first = pendingFloats.find((f) => f.span === 'page');
+                    if (first && !capActive && cap === undefined && bandStart && registeredBand
+                        && registeredBand.pageIndex === page.index && registeredBand.band === bandBefore) {
+                        const cols = bandColumns(page, bandBefore).filter((c) => c.bbox.height > 0.5);
+                        if (cols.length > 1 && !isBandLevel(cols) && cols.some((c) => c.blocks.length > 0)) {
+                            const lines = bandCapLines(cols, baselineGrid);
+                            const capBottom = bandTop(cols) + lines * baselineGrid;
+                            const bandBottom = Math.min(...cols.map((c) => columnBottom(c, uncappedBottoms)));
+                            const m = measureFloat(first.resourceId, page.contentArea.width, sliceOf(first));
+                            const figureFits = m !== null && capBottom + needFor(floatGapPx, m.height, floatGapPx) <= bandBottom + 0.01;
+                            if (figureFits) {
+                                bandCapProposals.set(startIdx, {
+                                    kind: 'span',
+                                    startContentIndex: bandStart.contentIndex,
+                                    startPart: bandStart.part,
+                                    lines,
+                                    retries: 0,
+                                });
+                            }
+                            else {
+                                proposeTrailingCap(startIdx);
+                            }
+                        }
+                    }
+                    tryPlacePendingFloatsOnCurrentPage();
+                    drainPendingFloats();
+                    if (cursor.pageIndex !== pageBefore || currentBand(doc.pages[cursor.pageIndex], cursor) !== bandBefore) {
+                        // A figure took a page ahead and the box follows it there. A
+                        // band cut level for it (trailing cap) counts as delivered —
+                        // the columns stay cut — and balancing never stretches the
+                        // page's last column back to the bottom. A span cap that could
+                        // not seat the figure is left undelivered for the driver to
+                        // grow or drop.
+                        if (capActive && cap?.kind === 'trailing')
+                            spanPlacedInBand.add(startIdx);
+                        if (doc.pages[pageBefore].columns.some((c) => c.blocks.length > 0))
+                            forcedBreakPages.add(pageBefore);
+                    }
+                    capActive = false;
+                }
+                page = doc.pages[cursor.pageIndex];
+            }
             const fit = forceHere ? (measureBand(true) ?? measureBand(false)) : measureBand(!capActive);
             let action = null;
             if (fit) {
@@ -894,21 +1347,30 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         band = measureBand(false);
                 }
                 if (band) {
-                    const fragment = splitCalloutFragment(L, from, page.contentArea.width, band.roomPx - band.spacing, frameId, continuation);
+                    const fragment = splitCalloutFragment(L, from, page.contentArea.width, band.roomPx - band.spacing, frameId, continuation, style.splitMinLines);
                     if (fragment) {
                         action = { kind: 'split', fit: band, need: needFor(band.spacing, fragment.result.totalHeight, 0), fragment };
                     }
                 }
             }
-            if (!action && forceHere && fit)
+            if (!action && forceHere && fit) {
                 action = { kind: 'whole', fit, need: fit.need, result };
+                (doc.warnings ??= []).push({
+                    kind: 'calloutOverflow',
+                    pageIndex: cursor.pageIndex,
+                    columnIndex: cursor.columnIndex,
+                    sourceStart: contentBlocks[startIdx].sourceStart + bodyOffset,
+                    sourceEnd: contentBlocks[plan.endIdx].sourceEnd + bodyOffset,
+                    overflowPx: Math.max(0, fit.spacing + result.totalHeight - fit.roomPx),
+                });
+            }
             if (action) {
                 if (capActive) {
                     uncapBand(action.fit.cols, uncappedBottoms);
                     spanPlacedInBand.add(startIdx);
                 }
                 const placed = action.kind === 'whole' ? action.result : action.fragment.result;
-                const to = action.kind === 'whole' ? L.children.length : action.fragment.to;
+                const to = action.kind === 'whole' ? L.end : action.fragment.to;
                 if (part > 0 || action.kind === 'split')
                     markFragment(placed, part, action.kind === 'split');
                 const spanCol = closeBandAndInsertSpan(page, action.fit.cols, action.fit.cutY, placed.frame, action.need, cursor, action.fit.spacing, placed.totalHeight);
@@ -945,13 +1407,23 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     // (or, for a splittable box, for the whole box flush with the
                     // band bottom).
                     const cols = bandColumns(page, currentBand(page, cursor));
-                    const lines = bandCapLines(cols, baselineGrid);
-                    const capBottom = bandTop(cols) + lines * baselineGrid;
+                    // A column holding only a figure at its head must keep that slot
+                    // in the capped pass: the cut can go no higher than the band the
+                    // figure takes, or the figure falls off the page and the box after it.
+                    const top = bandTop(cols);
+                    const floatHeads = cols
+                        .filter((c) => c.blocks.length === 0 && reservedOf(c).top > 0)
+                        .map((c) => Math.ceil((c.bbox.y - top - 0.01) / baselineGrid));
+                    const lines = Math.max(bandCapLines(cols, baselineGrid), ...floatHeads);
+                    const capBottom = top + lines * baselineGrid;
                     const spacing = Math.max(pendingSpacing, result.marginTopPx);
                     const need = needFor(spacing, result.totalHeight, result.marginBottomPx);
                     const bandBottom = Math.min(...cols.map((c) => columnBottom(c, uncappedBottoms)));
+                    // A splittable box is worth the cut when its head fits flush with
+                    // the band bottom, the rest going on to the next page.
                     const fitsAfterCut = capBottom + need + minRoomPx <= bandBottom + 0.01
-                        || (splittable && capBottom + needFor(spacing, result.totalHeight, 0) <= bandBottom + 0.01);
+                        || (splittable && capBottom + needFor(spacing, result.totalHeight, 0) <= bandBottom + 0.01)
+                        || (splittable && splitCalloutFragment(L, from, page.contentArea.width, bandBottom - capBottom - spacing, frameId, continuation, style.splitMinLines) !== null);
                     if (fitsAfterCut) {
                         bandCapProposals.set(startIdx, {
                             kind: 'span',
@@ -970,7 +1442,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     proposeTrailingCap(startIdx);
                     markForcedBreak();
                 }
-                else if (capActive && cap.kind === 'trailing') {
+                else if (capActive && cap?.kind === 'trailing') {
                     // Reached inside the band cut level for it: delivered even though
                     // the box moves on — the columns stay cut.
                     spanPlacedInBand.add(startIdx);
@@ -1195,7 +1667,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         const firstFrameId = `block-${blockIdCounter++}`;
         const { span, placement } = resolveCalloutAttrs(style, plan.attrs);
         const L = makeCalloutLayouter(startIdx, plan, style);
-        const layoutAt = (width) => L.layoutRange(0, L.children.length, width, firstFrameId, false);
+        const layoutAt = (width) => L.layoutRange(CUT_START, L.end, width, firstFrameId, false);
         // Fixed boxes leave the flow entirely.
         if (placement === 'fixed') {
             placeCalloutFixed(startIdx, plan, style, layoutAt);
@@ -1213,22 +1685,42 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             }
         }
         const splittable = !style.keepTogether;
-        let from = 0;
+        let from = CUT_START;
         let part = 0;
         let frameId = firstFrameId;
+        /** Times the box left an EMPTY short column (see below) — bounded. */
+        let shortColumnMoves = 0;
         for (;;) {
             let curCol = currentColumn(doc, cursor);
             const continuation = part > 0;
-            const result = L.layoutRange(from, L.children.length, curCol.bbox.width, frameId, continuation);
-            const spacing = curCol.blocks.length === 0 ? 0 : Math.max(pendingSpacing, result.marginTopPx);
+            const result = L.layoutRange(from, L.end, curCol.bbox.width, frameId, continuation);
+            // Column balancing: a box closing its column takes the column's gap
+            // above it (the trailing-callout lever), so its foot lands on the
+            // last grid slot — level with the column beside it. Any fragment
+            // qualifies, as long as something sits above it to push down from:
+            // text, or the float band at the head of an otherwise empty column.
+            const balanceBefore = curCol.blocks.length > 0 || reservedOf(curCol).top > 0
+                ? (balanceExtraPx?.get(balanceKey(startIdx, part)) ?? 0)
+                : 0;
+            const spacing = (curCol.blocks.length === 0 ? 0 : Math.max(pendingSpacing, result.marginTopPx)) + balanceBefore;
             const roomPx = curCol.availableHeight - spacing;
             let fragment = null;
             if (result.totalHeight > roomPx + 0.01) {
                 // The (rest of the) box does not fit the column: a splittable box
                 // leaves the head that fits here…
                 if (splittable)
-                    fragment = splitCalloutFragment(L, from, curCol.bbox.width, roomPx, frameId, continuation);
-                if (!fragment && curCol.blocks.length > 0) {
+                    fragment = splitCalloutFragment(L, from, curCol.bbox.width, roomPx, frameId, continuation, style.splitMinLines);
+                // …otherwise it moves whole to the next column — also out of an
+                // EMPTY column that float bands or a band cap have cut short, when
+                // a full column would hold it (bounded, so a run of short columns
+                // cannot make it wander forever). Only a box taller than a full
+                // column is placed anyway, overflowing (a layout warning says so).
+                const shortColumn = shortColumnMoves < 4
+                    && curCol.bbox.height < contentArea.height - baselineGrid
+                    && result.totalHeight <= contentArea.height + 0.01;
+                if (!fragment && (curCol.blocks.length > 0 || shortColumn)) {
+                    if (curCol.blocks.length === 0)
+                        shortColumnMoves++;
                     // …otherwise it moves whole to the next column. Keep-with-next: a
                     // run of headings at the column's tail travels with the box.
                     // Skipped when the column holds nothing else (rolling back again
@@ -1249,13 +1741,21 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         return (rolledBack[0].contentIndex ?? startIdx - rolledBack.length) - 1;
                     }
                     advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
-                    curCol = currentColumn(doc, cursor);
-                    // Columns of different widths (oneAndHalf): re-lay out for the new one.
-                    if (Math.abs(curCol.bbox.width - result.width) > 0.01 && style.width !== 'auto') {
-                        continue;
-                    }
+                    // Try the next column afresh: it may be short too (a float band
+                    // reserved on the page it opened), or of another width (oneAndHalf).
+                    continue;
                 }
                 // An empty column that is still too short: placed anyway, overflowing.
+                if (!fragment && curCol.blocks.length === 0 && result.totalHeight > curCol.availableHeight - spacing + 0.01) {
+                    (doc.warnings ??= []).push({
+                        kind: 'calloutOverflow',
+                        pageIndex: cursor.pageIndex,
+                        columnIndex: cursor.columnIndex,
+                        sourceStart: contentBlocks[startIdx].sourceStart + bodyOffset,
+                        sourceEnd: contentBlocks[plan.endIdx].sourceEnd + bodyOffset,
+                        overflowPx: result.totalHeight + spacing - curCol.availableHeight,
+                    });
+                }
             }
             // Floats first-referenced inside the box still enqueue in reading order
             // (only once the box is committed, so a keep-with-next replay does not
@@ -1264,10 +1764,17 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 for (let i = startIdx + 1; i <= plan.endIdx; i++)
                     enqueueFloatsFor(i);
             const placed = fragment ? fragment.result : result;
-            const to = fragment ? fragment.to : L.children.length;
+            const to = fragment ? fragment.to : L.end;
             if (part > 0 || fragment)
                 markFragment(placed, part, fragment !== null);
-            const spacingBefore = curCol.blocks.length === 0 ? 0 : Math.max(pendingSpacing, placed.marginTopPx);
+            const spacingBefore = (curCol.blocks.length === 0 ? 0 : Math.max(pendingSpacing, placed.marginTopPx)) + balanceBefore;
+            if (balanceBefore > 0)
+                addBalanceExtra(curCol, balanceBefore);
+            // Spacing collapses at a column top, so the lever's push under a
+            // float band is consumed here: the box then opens that far down.
+            if (balanceBefore > 0 && curCol.blocks.length === 0) {
+                curCol.availableHeight = Math.max(0, curCol.availableHeight - balanceBefore);
+            }
             enterBand(startIdx, 0);
             placeAtomicBlock(placed.frame, placed.totalHeight, spacingBefore, cursor, doc, resolved, contentArea, pageWidthPx, pageHeightPx);
             enterBand(startIdx, 0);
@@ -1301,7 +1808,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         // order. Then enqueue the floats first-referenced in this block, so the
         // next page opened while placing it (or any later block) reserves their
         // band and the next iteration offers them the slots that follow.
-        tryPlacePendingFloatsOnCurrentPage();
+        tryPlacePendingFloatsOnCurrentPage(spanBoxAt(blockIdx), blockIdx);
         enqueueFloatsFor(blockIdx);
         // --- Directives ----------------------------------------------------
         if (rawBlock.type === 'directive') {
@@ -1420,7 +1927,9 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 // takes every pending float first — in the current page's free
                 // slots, else on pages opened ahead of it — so no float escapes
                 // past it. The page stays balanceable (no forced break).
-                if (pickCalloutStyle(resolved.calloutStyles, plan.attrs.type).floatBarrier) {
+                // A page-span barrier box drains inside `placeCalloutSpan`, once
+                // the page-span figures before it have taken the band cut.
+                if (pickCalloutStyle(resolved.calloutStyles, plan.attrs.type).floatBarrier && !spanBoxAt(blockIdx)) {
                     tryPlacePendingFloatsOnCurrentPage();
                     drainPendingFloats();
                 }
@@ -1614,6 +2123,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         // A justified line a link leaves with too few spaces is set ragged.
         let remainingLines = [...raggedUrlLines(measured.lines, style.textAlign, rawBlock.text)];
         let partIndex = 0;
+        /** Times this block left an EMPTY short column (see `shortColumn`) —
+         *  bounded so a page whose columns are all short (footnotes, design
+         *  bands) cannot make it wander forever. */
+        let shortColumnMoves = 0;
         // "Keep with next" for colon-introduced lists: a paragraph ending in `:`
         // followed directly by a list acts as a lead-in title — the colon-bearing
         // line must share a column with the first list item. Only checked for the
@@ -1642,8 +2155,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     // page top.
                     if (vdtType === 'heading') {
                         const extraPx = balanceExtraPx?.get(blockIdx);
-                        if (extraPx)
+                        if (extraPx) {
                             spacingBefore += extraPx;
+                            addBalanceExtra(curCol, extraPx);
+                        }
                     }
                 }
                 else if (vdtType === 'listItem') {
@@ -1657,10 +2172,26 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 // handled inside the heading branch above (after margin collapsing).
                 if (vdtType !== 'heading' && vdtType !== 'mathDisplay' && partIndex === 0) {
                     const extraPx = balanceExtraPx?.get(blockIdx);
-                    if (extraPx)
+                    if (extraPx) {
                         spacingBefore += extraPx;
+                        addBalanceExtra(curCol, extraPx);
+                    }
+                }
+            }
+            else if (partIndex === 0 && reservedOf(curCol).top > 0) {
+                // Column balancing: extra grid lines between the float band at the
+                // head of this column and its first block (the after-float lever).
+                const extraPx = balanceExtraPx?.get(blockIdx);
+                if (extraPx) {
+                    spacingBefore += extraPx;
+                    addBalanceExtra(curCol, extraPx);
                 }
             }
+            // A loose paragraph's extra line is balancing height too (it lands
+            // whole in this column — loose candidates are never split parts).
+            if (partIndex === 0 && tryLoose && looseLines !== undefined && typeof looseOutcome.get(blockIdx) === 'number') {
+                addBalanceExtra(curCol, looseLines * style.lineHeightPx);
+            }
             const effectiveAvailable = curCol.availableHeight - spacingBefore;
             const linesPerAvailable = Math.floor(effectiveAvailable / style.lineHeightPx);
             // Math display blocks carry their natural pixel height on the single
@@ -1704,7 +2235,9 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 && curCol.blocks.length > 0) {
                 const usedHeight = (curCol.bbox.height - curCol.availableHeight) + spacingBefore;
                 const paragraphBottom = usedHeight + totalRemainHeight;
-                const availableAfter = curCol.bbox.height - paragraphBottom;
+                // Slack after the paragraph as the plain pass saw it: the height
+                // balancing added above in this column is not room the list lost.
+                const availableAfter = curCol.bbox.height - paragraphBottom + (balanceExtraInColumn.get(curCol) ?? 0);
                 const nextListKind = nextBlock?.listKind ?? 'unordered';
                 const nextListMarginDim = nextListKind === 'ordered'
                     ? resolved.orderedLists.marginTop
@@ -1784,6 +2317,16 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     // headingRunCount === curCol.blocks.length: fall through to place.
                 }
             }
+            // A block opening a column normally stays (no column can take it any
+            // better), except in a column at least a line shorter than the content
+            // area — the band under a page-span box, or a column cut by a float:
+            // a heading that fits there alone, or a block that does not fit there
+            // but would fit a full column, opens the next column instead (the move
+            // count is bounded besides). A column cut by a band cap is short on
+            // purpose — its content is meant to end at the cut.
+            const shortColumn = shortColumnMoves < 4
+                && !uncappedBottoms.has(curCol)
+                && curCol.bbox.height < contentArea.height - baselineGrid;
             // Block fits in current column
             if (effectiveRemainHeight <= effectiveAvailable) {
                 // Heading keep-with-next: never leave a heading as the last block of a
@@ -1800,7 +2343,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     && resolved.headings.keepWithNext
                     && !nextIsHeading
                     && nextBlock !== null
-                    && curCol.blocks.length > 0) {
+                    && (curCol.blocks.length > 0 || shortColumn)) {
                     const wouldUsedHeight = (curCol.bbox.height - curCol.availableHeight) + spacingBefore;
                     const naturalBottom = wouldUsedHeight + effectiveRemainHeight + style.marginBottomPx;
                     const snappedBottom = shouldSnapToGrid
@@ -1812,6 +2355,8 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         : 1;
                     const minSpaceAfter = minLinesNeeded * bodyStyle.lineHeightPx;
                     if (remainAfterHeading < minSpaceAfter) {
+                        if (curCol.blocks.length === 0)
+                            shortColumnMoves++;
                         // Roll back any immediately-preceding heading blocks in this
                         // column so they travel with this one.
                         const rolledBack = rollbackTrailingBlocks(curCol, doc.blocks, isFreeHeading);
@@ -1975,8 +2520,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 }
                 // choice.splitAt === 0: fall through to push whole paragraph to next column
             }
-            // Cannot split — advance to next column if current has content
-            if (curCol.blocks.length > 0) {
+            // Cannot split — advance to next column if current has content (or
+            // the column is a short band that cannot hold the block at all).
+            if (curCol.blocks.length > 0 || (shortColumn && effectiveRemainHeight <= contentArea.height)) {
+                if (curCol.blocks.length === 0)
+                    shortColumnMoves++;
                 // Heading keep-with-next (no-fit variant): when a heading can't fit
                 // in the current column and the column's tail is a run of headings,
                 // pull those headings along so they don't remain stranded as orphans
@@ -2099,17 +2647,67 @@ export function buildDocument(content, config, cache, options) {
     let bestScore = totalGapLines(best.doc, best.forcedBreakPages);
     let applied = { lines: new Map(), loose: new Map() };
     const failedLoose = new Set();
+    const failedLines = new Set();
     let converged = bestScore === 0;
+    /**
+     * A rejected pass moved content across a column break somewhere (a
+     * split paragraph whose head no longer fits, a float that lost its slot,
+     * a lead-in that left with its list…): every page after that point is
+     * re-flowed, gaps open elsewhere and a span cap may miss its band. The
+     * levers are meant to be local, so contain the damage: find the first
+     * column whose content changed and blacklist the levers this pass newly
+     * applied there (failing that, on its page; failing that, everywhere), so
+     * the next proposal keeps the working levers before it and tries again
+     * without the one that cascaded. Returns whether anything was blacklisted.
+     */
+    const containCascade = (next, proposal) => {
+        const div = firstDivergentColumn(best.doc, next.doc);
+        if (!div)
+            return false;
+        const newLines = [...proposal.lines].filter(([k, n]) => n > (applied.lines.get(k) ?? 0)).map(([k]) => k);
+        const newLoose = [...proposal.loose.keys()].filter((k) => !applied.loose.has(k));
+        if (newLines.length === 0 && newLoose.length === 0)
+            return false;
+        const gaps = collectColumnGaps(best.doc, best.forcedBreakPages);
+        const blacklist = (cands) => {
+            let hit = false;
+            for (const k of newLines)
+                if (!cands || cands.has(k)) {
+                    failedLines.add(k);
+                    hit = true;
+                }
+            for (const k of newLoose)
+                if (!cands || cands.has(k)) {
+                    failedLoose.add(k);
+                    hit = true;
+                }
+            return hit;
+        };
+        const inColumn = gaps
+            .filter((g) => g.pageIndex === div.pageIndex && g.columnIndex === div.columnIndex)
+            .flatMap((g) => g.candidates.map((c) => balanceKey(c.contentIndex, c.part ?? 0)));
+        if (blacklist(new Set(inColumn)))
+            return true;
+        const onPage = gaps
+            .filter((g) => g.pageIndex === div.pageIndex)
+            .flatMap((g) => g.candidates.map((c) => balanceKey(c.contentIndex, c.part ?? 0)));
+        if (blacklist(new Set(onPage)))
+            return true;
+        return blacklist(null);
+    };
     const balance = () => {
         while (!converged && passCount < MAX_BALANCING_PASSES) {
             const proposal = proposeBalanceLines(best.doc, best.forcedBreakPages, applied, {
                 maxLinesPerHeading: balancing.maxLinesPerHeading,
                 stretchAfterLists: balancing.stretchAfterLists,
                 maxLinesAfterList: balancing.maxLinesAfterList,
+                stretchAfterFloats: balancing.stretchAfterFloats,
+                maxLinesAfterFloat: balancing.maxLinesAfterFloat,
                 looseParagraphs: balancing.looseParagraphs,
                 maxLooseParagraphs: balancing.maxLooseParagraphs,
                 optimalLineBreaking: best.doc.config.bodyText.optimalLineBreaking,
                 failedLoose,
+                failedLines,
             });
             if (!proposal.changed) {
                 // No stretch point can absorb the remaining gaps — stable.
@@ -2153,11 +2751,16 @@ export function buildDocument(content, config, cache, options) {
                 converged = score === 0;
             }
             else {
-                // Plateau or regression. Retry when a loose candidate was just
-                // blacklisted (the proposer falls through to the next one), or when
-                // the new loose paragraphs gained their lines yet the layout did not
-                // improve (the gain landed elsewhere — drop them too). A pure spacing
-                // plateau means we're done: keep the best layout found so far.
+                // Plateau or regression. First contain a cascade: a lever that
+                // moved content across a column break is blacklisted and the loop
+                // retries without it. Otherwise retry when a loose candidate was
+                // just blacklisted (the proposer falls through to the next one), or
+                // when the new loose paragraphs gained their lines yet the layout
+                // did not improve (the gain landed elsewhere — drop them too). A
+                // pure spacing plateau means we're done: keep the best layout found
+                // so far.
+                if (containCascade(next, proposal))
+                    continue;
                 if (looseFailed.length > 0 || looseWon.length > 0) {
                     for (const k of looseWon)
                         failedLoose.add(k);