postext 0.3.29 → 0.3.31

package/dist/pipeline/build.js

@@ -16,15 +16,18 @@ 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, collectColumnGaps, firstDivergentColumn, 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';
+import { raggedLooseLines } from './raggedLines';
+/** Tolerance for "does this block fit" checks against a column's free
+ *  height, absorbing floating-point drift between grid multiples. */
+const FIT_EPS = 0.01;
 export class BuildCancelledError extends Error {
     constructor() {
         super('Build cancelled');
@@ -207,6 +210,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 +225,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 +238,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 +250,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 +263,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 +304,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 +320,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;
@@ -317,24 +353,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;
@@ -346,10 +494,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';
@@ -359,7 +522,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) {
@@ -373,7 +536,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             }
             else {
                 const capped = uncappedBottoms.get(col);
-                if (capped !== undefined) {
+                if (capped !== undefined && !anchorToCap) {
                     uncappedBottoms.set(col, capped - need);
                 }
                 else {
@@ -381,6 +544,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;
             }
@@ -391,7 +559,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
@@ -433,21 +615,76 @@ 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 = (preferTop = false) => {
+     *  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';
@@ -455,18 +692,24 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             // 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.
+            // 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) {
-                r = placeFloatInColumns(page, f, slot.cols, slot.position, slot.pageSpan, 'strict');
+                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
@@ -481,7 +724,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             return false;
         const plan = calloutPlan.get(idx);
         const style = plan ? pickCalloutStyle(resolved.calloutStyles, plan.attrs.type) : undefined;
-        if (!style || style.span !== 'page' || style.placement === 'fixed')
+        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;
@@ -494,12 +740,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
         }
     };
@@ -585,7 +831,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         for (const [spanIndex, cap] of bandCaps) {
             if (cap.startContentIndex !== contentIndex || cap.startPart !== part)
                 continue;
-            applyBandCap(bandColumns(page, band), cap.lines * baselineGrid, uncappedBottoms, cap.zone);
+            applyBandCap(bandColumns(page, band), cap.lines * baselineGrid, uncappedBottoms, cap.zone, cap.kind === 'trailing');
             activeCap = { spanIndex, pageIndex: page.index, band };
             bandCapsApplied.add(spanIndex);
             break;
@@ -620,13 +866,16 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         const cols = bandColumns(page, band).filter((c) => c.bbox.height > 0.5);
         if (cols.length < 2 || cols.some((c) => c.forcedBreak))
             return;
-        if (bandCaps?.has(boundaryIndex)) {
-            if (activeCap && activeCap.spanIndex === boundaryIndex
-                && activeCap.pageIndex === page.index && activeCap.band === band) {
-                spanPlacedInBand.add(boundaryIndex);
-            }
+        if (activeCap && activeCap.spanIndex === boundaryIndex
+            && activeCap.pageIndex === page.index && activeCap.band === band) {
+            spanPlacedInBand.add(boundaryIndex);
             return;
         }
+        // A cap in force for this boundary that did not open the band the
+        // boundary is reached in (an earlier cap moved the flow under it, or
+        // its own band overflowed) still gets a fresh proposal below: the
+        // driver replaces a cap that no longer applies with it, and ignores it
+        // while retrying an applied cap a line taller.
         if (activeCap && activeCap.pageIndex === page.index && activeCap.band === band)
             return;
         if (!cols.some((c) => c.blocks.length > 0))
@@ -637,11 +886,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 } : {}),
         });
@@ -734,6 +994,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 = [];
@@ -743,12 +1004,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,
@@ -756,49 +1020,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;
@@ -879,9 +1158,8 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
          *  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, the slack under
-         *  the figure being the compositor's usual trade; a figure referenced
-         *  earlier keeps the cap route, which flows text under it. */
+         *  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]))
@@ -897,13 +1175,69 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 return false;
             if (!isBandLevel(textCols))
                 return false;
-            const textBottom = bandUsedBottom(textCols);
             const before = lastBlockBefore();
-            return floatOnly.every((c) => c.bbox.y <= textBottom + baselineGrid + 0.5 && topFloatRefOf.get(c) === before);
+            // 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;
         };
-        /** 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;
+        /** 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):
@@ -912,7 +1246,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
@@ -936,11 +1270,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) {
@@ -960,21 +1353,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);
@@ -1011,13 +1413,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',
@@ -1036,7 +1448,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);
@@ -1261,7 +1673,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);
@@ -1279,22 +1691,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
@@ -1315,13 +1747,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
@@ -1330,10 +1770,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);
@@ -1367,7 +1814,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(spanBoxAt(blockIdx));
+        tryPlacePendingFloatsOnCurrentPage(spanBoxAt(blockIdx), blockIdx);
         enqueueFloatsFor(blockIdx);
         // --- Directives ----------------------------------------------------
         if (rawBlock.type === 'directive') {
@@ -1486,8 +1933,10 @@ 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) {
-                    tryPlacePendingFloatsOnCurrentPage(spanBoxAt(blockIdx));
+                // 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();
                 }
                 // `span: 'page'` boxes in multi-column layouts branch to the
@@ -1506,11 +1955,16 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 ? paragraphContainers.byId.get(rawBlock.containerId)
                 : undefined;
             if (pc) {
+                // Margins collapse with the pending spacing; a negative one pulls
+                // the flow up past it instead (the container starts inside the
+                // space the previous block left, or the next block inside the
+                // container's).
+                const collapse = (margin) => margin < 0 ? pendingSpacing + margin : Math.max(pendingSpacing, margin);
                 if (rawBlock.type === 'containerStart') {
-                    pendingSpacing = Math.max(pendingSpacing, pc.marginTopPx);
+                    pendingSpacing = collapse(pc.marginTopPx);
                 }
                 else if (contentBlocks[blockIdx - 1]?.type !== 'paragraph') {
-                    pendingSpacing = Math.max(pendingSpacing, pc.marginBottomPx);
+                    pendingSpacing = collapse(pc.marginBottomPx);
                 }
             }
             continue;
@@ -1677,8 +2131,9 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         // List items may split too — orphan/widow protection per-list is gated by
         // `avoidOrphansInLists` / `avoidWidowsInLists`; bullet stays on first part.
         const canSplit = vdtType === 'paragraph' || vdtType === 'blockquote' || vdtType === 'listItem';
-        // A justified line a link leaves with too few spaces is set ragged.
-        let remainingLines = [...raggedUrlLines(measured.lines, style.textAlign, rawBlock.text)];
+        // A justified line the breaker could not fill (a link breaking at its
+        // joints, a last word that cannot come up) is set ragged, not stretched.
+        let remainingLines = [...raggedLooseLines(measured.lines, style.textAlign)];
         let partIndex = 0;
         /** Times this block left an EMPTY short column (see `shortColumn`) —
          *  bounded so a page whose columns are all short (footnotes, design
@@ -1808,7 +2263,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         : 1;
                     const splitAt = remainingLines.length - 1;
                     if (splitAt >= effectiveWidowMin) {
-                        if (spacingBefore > 0)
+                        if (spacingBefore !== 0)
                             curCol.availableHeight -= spacingBefore;
                         const splitLines = remainingLines.slice(0, splitAt);
                         const blk = createVDTBlock(id, vdtType, style.fontString, style.color, style.textAlign);
@@ -1884,8 +2339,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             const shortColumn = shortColumnMoves < 4
                 && !uncappedBottoms.has(curCol)
                 && curCol.bbox.height < contentArea.height - baselineGrid;
-            // Block fits in current column
-            if (effectiveRemainHeight <= effectiveAvailable) {
+            // Block fits in current column (a hair of tolerance: a capped column
+            // and the grid lines balancing adds above a block differ by floating
+            // point noise, which must not push the block over the cut).
+            if (effectiveRemainHeight <= effectiveAvailable + FIT_EPS) {
                 // 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,
@@ -1930,8 +2387,8 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         continue;
                     }
                 }
-                // Consume spacing
-                if (spacingBefore > 0) {
+                // Consume spacing (negative: a container margin pulling the block up)
+                if (spacingBefore !== 0) {
                     curCol.availableHeight -= spacingBefore;
                 }
                 const partId = partIndex === 0 ? id : `${id}-cont-${partIndex}`;
@@ -1994,7 +2451,9 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     // the grid (e.g. marginBottom is an exact multiple of baselineGrid),
                     // don't round up to the next line.
                     const snappedBottom = Math.ceil((naturalBottom - 0.01) / baselineGrid) * baselineGrid;
-                    h = snappedBottom - usedHeight;
+                    // A negative margin below a container tail may snap the flow back
+                    // above the text's own bottom; never below the block's top.
+                    h = Math.max(0, snappedBottom - usedHeight);
                 }
                 placeBlockInColumn(blk, h, curCol, cursor);
                 finalizeListItem(blk, partIndex === 0);
@@ -2040,8 +2499,8 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     slackWeight: resolved.bodyText.slackWeight,
                 });
                 if (choice.splitAt > 0) {
-                    // Consume spacing
-                    if (spacingBefore > 0) {
+                    // Consume spacing (negative: a container margin pulling the block up)
+                    if (spacingBefore !== 0) {
                         curCol.availableHeight -= spacingBefore;
                     }
                     const partId = partIndex === 0 ? id : `${id}-cont-${partIndex}`;
@@ -2242,12 +2701,12 @@ export function buildDocument(content, config, cache, options) {
         };
         const inColumn = gaps
             .filter((g) => g.pageIndex === div.pageIndex && g.columnIndex === div.columnIndex)
-            .flatMap((g) => g.candidates.map((c) => c.contentIndex));
+            .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) => c.contentIndex));
+            .flatMap((g) => g.candidates.map((c) => balanceKey(c.contentIndex, c.part ?? 0)));
         if (blacklist(new Set(onPage)))
             return true;
         return blacklist(null);