postext 0.3.28 → 0.3.29

package/dist/pipeline/build.js

@@ -22,7 +22,7 @@ import { enumerateCurrentPageSlots, measureFloatBand, columnHasFloatBand, fitsSt
 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 } from './columnBalancing';
 import { applyBandCap, uncapBand, columnBottom, bandCapLines, bandTop, resolveBandCaps, resolveTrailingCaps, bandCapLinesAroundZone, } from './bandCaps';
 import { raggedUrlLines } from './raggedUrl';
 export class BuildCancelledError extends Error {
@@ -303,6 +303,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. */
@@ -366,6 +369,7 @@ 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);
@@ -440,14 +444,21 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
      *  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 = () => {
+    const tryPlacePendingFloatsOnCurrentPage = (preferTop = false) => {
         if (pendingFloats.length === 0)
             return;
         const page = doc.pages[cursor.pageIndex];
         for (let i = 0; i < pendingFloats.length;) {
             const f = pendingFloats[i];
             let r = 'defer';
-            for (const slot of enumerateCurrentPageSlots(page, cursor.columnIndex, f, capKindOf)) {
+            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.
+            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 (r !== 'defer')
                     break;
@@ -461,6 +472,20 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     /** 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 || style.span !== 'page' || style.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
@@ -531,6 +556,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();
@@ -835,6 +873,34 @@ 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;
         };
+        /** 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, the slack under
+         *  the figure being the compositor's usual trade; 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 textBottom = bandUsedBottom(textCols);
+            const before = lastBlockBefore();
+            return floatOnly.every((c) => c.bbox.y <= textBottom + baselineGrid + 0.5 && topFloatRefOf.get(c) === before);
+        };
         /** 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;
@@ -855,7 +921,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);
@@ -1301,7 +1367,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));
         enqueueFloatsFor(blockIdx);
         // --- Directives ----------------------------------------------------
         if (rawBlock.type === 'directive') {
@@ -1421,7 +1487,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 // 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();
+                    tryPlacePendingFloatsOnCurrentPage(spanBoxAt(blockIdx));
                     drainPendingFloats();
                 }
                 // `span: 'page'` boxes in multi-column layouts branch to the
@@ -1614,6 +1680,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 +1712,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 +1729,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 +1792,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 +1874,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 +1900,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 +1912,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 +2077,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 +2204,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) => c.contentIndex));
+        if (blacklist(new Set(inColumn)))
+            return true;
+        const onPage = gaps
+            .filter((g) => g.pageIndex === div.pageIndex)
+            .flatMap((g) => g.candidates.map((c) => c.contentIndex));
+        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 +2308,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);