postext 0.3.35 → 0.3.37

package/dist/pipeline/build.js

@@ -6,7 +6,10 @@ import { parseMarkdownMemo } from '../parse';
 import { buildPageLabels, computeHeadingNumbers, } from '../numbering';
 import { extractFrontmatter } from '../frontmatter';
 import { initHyphenator } from '../measure';
-import { resolveAllConfig, computeBaselineGrid, buildHeadingLevelMap } from './config';
+import { resolveAllConfig, computeBaselineGrid } from './config';
+import { createHeadingLevelResolver, deriveSectionGeometryConfig, deriveSectionMeasureContext, headingIsNumbered, headingStyleOf, planHeadingSections, } from './headingStyles';
+import { computeOutline, hasTocDirective, outlineFromDoc, sameOutline } from './outline';
+import { expandTocDirectives } from './toc';
 import { resolveBodyStyle, resolveBlockquoteStyle } from './styles';
 import { computeLevelIndentsPx, computeOrderedLevelIndentsPx, computeOrderedListRunMetrics, } from './lists';
 import { resetLinePositions, createPageWithColumns, currentColumn, advanceToNextColumn, advanceToNextPageBoundary, enforcePageParity, placeBlockInColumn, placeAtomicBlock, createPartPage, pageHasContent, pageIsOccupied, bandColumns, currentBand, isBandLevel, bandUsedBottom, closeBandAndInsertSpan, } from './placement';
@@ -22,7 +25,7 @@ import { enumerateCurrentPageSlots, measureFloatBand, columnHasFloatBand, fitsSt
 import { computeHeadingContext, computeResourceNumbering, } from './resourceNumbering';
 import { defaultResourceTypes } from '../defaults/resourceTypes';
 import { buildHeadersAndFooters, measureHeadingAdvancedDesignHeight } from './headerFooter';
-import { totalGapLines, proposeBalanceLines, collectColumnGaps, firstDivergentColumn, MAX_BALANCING_PASSES, balanceKey } from './columnBalancing';
+import { proposeBalanceLines, collectColumnGaps, firstDivergentColumn, gapLinesIn, pageSegments, MAX_BALANCING_PASSES, MAX_BALANCING_PASSES_PER_DOCUMENT, balanceKey } from './columnBalancing';
 import { applyBandCap, uncapBand, columnBottom, bandCapLines, bandTop, resolveBandCaps, resolveTrailingCaps, bandCapLinesAroundZone, } from './bandCaps';
 import { raggedLooseLines } from './raggedLines';
 /** Tolerance for "does this block fit" checks against a column's free
@@ -97,7 +100,8 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     const looseOutcome = new Map();
     // Lines gained so far per column budget group (see `LooseBudget`).
     const looseGained = new Map();
-    const headingLevelByNumber = buildHeadingLevelMap(resolved);
+    // Level configs with heading-style overrides merged in (`{style="…"}`).
+    const headingLevels = createHeadingLevelResolver(resolved);
     const dpi = resolved.page.dpi;
     // Initialize hyphenator if needed (body text, or any justified paragraph
     // style that hyphenates — they share the document locale).
@@ -123,7 +127,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     if (continuation?.part)
         doc.partStart = continuation.part;
     const pageMetrics = computePageMetrics(resolved);
-    const { pageWidthPx, pageHeightPx, trimOffset, contentArea } = pageMetrics;
+    const { pageWidthPx, pageHeightPx, trimOffset } = pageMetrics;
+    // The geometry pages are opened with: the document's, or — inside a
+    // styled section with its own margins / layout — the section's.
+    let contentArea = pageMetrics.contentArea;
+    let geomResolved = resolved;
     // Page/bleed frames for design elements anchored to `'page'` / `'bleed'`.
     const designFrames = { page: pageMetrics.trimBox, bleed: pageMetrics.bleedBox };
     doc.trimOffset = trimOffset;
@@ -133,22 +141,29 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     // Extract frontmatter, then parse the remaining markdown body
     const { metadata: frontmatterMeta, content: markdownBody, contentOffset: bodyOffset } = extractFrontmatter(content.markdown);
     doc.metadata = { ...(content.metadata ?? {}), ...frontmatterMeta };
-    const contentBlocks = parseMarkdownMemo(markdownBody);
+    const parsedBlocks = parseMarkdownMemo(markdownBody);
+    const headingStart = continuation?.headings;
+    // `:::toc` expands into the entries of the book's outline — the one the
+    // host supplied, else this document's own (page labels unknown on the
+    // first pass; `buildDocument` lays the document out again with them).
+    const outline = content.outline
+        ?? (hasTocDirective(parsedBlocks) ? computeOutline(parsedBlocks, resolved, headingStart) : undefined);
+    const contentBlocks = expandTocDirectives(parsedBlocks, outline, resolved);
+    const isNumbered = (b) => headingIsNumbered(b, resolved);
     const headingTemplates = {};
     for (const lvl of resolved.headings.levels) {
         if (lvl.numberingTemplate && lvl.numberingTemplate.length > 0) {
             headingTemplates[lvl.level] = lvl.numberingTemplate;
         }
     }
-    const headingStart = continuation?.headings;
-    const headingPrefixes = computeHeadingNumbers(contentBlocks, headingTemplates, headingStart ? [headingStart.h1, headingStart.h2, headingStart.h3, headingStart.h4, headingStart.h5, headingStart.h6] : undefined);
+    const headingPrefixes = computeHeadingNumbers(contentBlocks, headingTemplates, headingStart ? [headingStart.h1, headingStart.h2, headingStart.h3, headingStart.h4, headingStart.h5, headingStart.h6] : undefined, isNumbered);
     // Resource numbering — computed up front (before the placement loop) so that
     // captions and inline `:ref`s can resolve their rendered number strings
     // before measurement. Numbering follows order of first reference in the
     // document.
     const resourceTypes = config?.resourceTypes ?? defaultResourceTypes();
     const resources = content.resources ?? [];
-    const headingContext = computeHeadingContext(contentBlocks, headingStart);
+    const headingContext = computeHeadingContext(contentBlocks, headingStart, isNumbered);
     const resourceNumbering = computeResourceNumbering(contentBlocks, resourceTypes, resources, headingContext, continuation ? { counters: continuation.resourceCounters, numbered: continuation.resourceNumbers } : undefined);
     // Lookups threaded into block-kind resolution + measurement.
     const resourceById = new Map();
@@ -173,6 +188,9 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     const calloutPlan = planCallouts(contentBlocks);
     // `:::part` ranges: start/end marker indices and the enclosed blocks.
     const partPlan = planParts(contentBlocks);
+    // Styled sections (`{style="…"}` headings): geometry, running heads and
+    // body typography per content-block index.
+    const sectionPlan = planHeadingSections(contentBlocks, resolved);
     // --- Float planning (issue #49 — resources float to page bands) ----------
     // A resource is incorporated by its first reference (an inline `:ref` or a
     // `::resource` directive, whichever comes first in reading order). Floated
@@ -837,7 +855,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             const before = floatsPlaced;
             const startPageIndex = cursor.pageIndex;
             do {
-                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
             } while (cursor.pageIndex === startPageIndex);
             if (floatsPlaced === before)
                 break; // safety: no progress
@@ -846,6 +864,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     // Everything per-block measurement needs that is constant for this pass.
     const measureCtx = {
         resolved,
+        headingLevels,
         bodyStyle,
         blockquoteStyle,
         headingPrefixes,
@@ -869,6 +888,59 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         : measureCtx;
     // Placement cursor
     const cursor = { pageIndex: 0, columnIndex: 0 };
+    // Blocks inside a styled section with a body style measure with it.
+    const sectionMeasureCtxs = new Map();
+    const sectionMeasureCtx = (style) => {
+        if (!style?.bodyStyle)
+            return measureCtx;
+        let ctx = sectionMeasureCtxs.get(style);
+        if (!ctx) {
+            ctx = deriveSectionMeasureContext(measureCtx, style);
+            sectionMeasureCtxs.set(style, ctx);
+        }
+        return ctx;
+    };
+    /** The styled section whose geometry the pages opened from now on take. */
+    let currentSection;
+    const enterSection = (style) => {
+        currentSection = style;
+        geomResolved = style ? deriveSectionGeometryConfig(resolved, style) : resolved;
+        contentArea = geomResolved === resolved ? pageMetrics.contentArea : computePageMetrics(geomResolved).contentArea;
+        // A page still empty takes the geometry right away — the document (or
+        // a chapter laid out on its own) opening with a styled heading.
+        const page = doc.pages[cursor.pageIndex];
+        if (page && !page.partInfo && cursor.columnIndex === 0
+            && !pageHasContent(page) && !(page.floats && page.floats.length > 0)) {
+            const fresh = createPageWithColumns(page.index, geomResolved, contentArea, pageWidthPx, pageHeightPx, pageIndexOffset);
+            if (page.blankForParity)
+                fresh.blankForParity = true;
+            if (page.blankForForce)
+                fresh.blankForForce = true;
+            doc.pages[cursor.pageIndex] = fresh;
+        }
+    };
+    /** Heading-style and contents-row stamps a placed block carries for the
+     *  running heads (`computeSectionStyles`) and the contents' part rows. */
+    const stampBlockExtras = (blk, raw) => {
+        if (raw.type === 'heading') {
+            const style = headingStyleOf(raw, resolved);
+            if (style) {
+                blk.headingStyleId = style.id;
+                if (!style.numbered)
+                    blk.unnumbered = true;
+            }
+        }
+        if (raw.toc?.kind === 'entry')
+            blk.tocEntry = true;
+        if (raw.toc?.kind === 'part') {
+            blk.tocPart = {
+                number: raw.toc.number,
+                title: raw.toc.title ?? '',
+                pageLabel: raw.toc.pageLabel ?? '',
+                ...(raw.toc.palette ? { palette: raw.toc.palette } : {}),
+            };
+        }
+    };
     let blockIdCounter = 0;
     let pendingSpacing = 0;
     // Pages whose break into the next page is explicit rather than natural
@@ -1029,11 +1101,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         if (curPage.partInfo && !pageHasContent(curPage)) {
             const startPageIndex = cursor.pageIndex;
             do {
-                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx);
             } while (cursor.pageIndex === startPageIndex);
             return;
         }
-        advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+        advanceToNextPageBoundary(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx);
     };
     // Page-numbering segments. The implicit first segment comes from
     // `cfg.page.pageNumbering`; `:::numbering` directives append more,
@@ -1049,18 +1121,27 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
     let pendingNumberingChange = null;
     let lastSeenPageIndex = 0;
     /** Commits any pending `:::numbering` change once we've crossed into a
-     *  new page. Called after every block iteration. */
+     *  new page — or while the current page is still empty: the directive at
+     *  the head of a chapter (or right after a page break) numbers the page
+     *  it opens, not the one after. Called after every block iteration. */
     const flushPendingNumberingAtBoundary = () => {
-        if (cursor.pageIndex > lastSeenPageIndex) {
-            if (pendingNumberingChange) {
+        if (pendingNumberingChange) {
+            const page = doc.pages[cursor.pageIndex];
+            const pageStillEmpty = !pageHasContent(page) && !(page.floats && page.floats.length > 0);
+            if (cursor.pageIndex > lastSeenPageIndex || pageStillEmpty) {
+                // A change already recorded for this page is replaced.
+                const last = pageNumberSegments[pageNumberSegments.length - 1];
+                if (last.startPageIndex === cursor.pageIndex && pageNumberSegments.length > 1)
+                    pageNumberSegments.pop();
                 pageNumberSegments.push({
                     startPageIndex: cursor.pageIndex,
                     ...pendingNumberingChange,
                 });
                 pendingNumberingChange = null;
             }
-            lastSeenPageIndex = cursor.pageIndex;
         }
+        if (cursor.pageIndex > lastSeenPageIndex)
+            lastSeenPageIndex = cursor.pageIndex;
     };
     /** Heading blocks that are not part of a callout — the only ones the
      *  keep-with-next rollbacks may pull along (a callout is one unbreakable
@@ -1508,7 +1589,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 frameId = `block-${blockIdCounter++}`;
                 const startPageIndex = cursor.pageIndex;
                 do {
-                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                    advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                 } while (cursor.pageIndex === startPageIndex);
                 forceHere = true;
                 continue;
@@ -1580,7 +1661,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 pendingSpacing = 0;
                 const startPageIndex = cursor.pageIndex;
                 do {
-                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                    advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                 } while (cursor.pageIndex === startPageIndex);
                 page = doc.pages[cursor.pageIndex];
             }
@@ -1610,7 +1691,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 continue;
             }
             if (b.type === 'heading' && b.level) {
-                const level = headingLevelByNumber.get(b.level);
+                const level = headingLevels.forBlock(b);
                 return level?.breakBefore?.enabled === true || level?.span === 'page';
             }
             return false;
@@ -1716,7 +1797,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             pendingSpacing = 0;
             const startPageIndex = cursor.pageIndex;
             do {
-                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
             } while (cursor.pageIndex === startPageIndex);
             page = doc.pages[cursor.pageIndex];
             fit = attempt(page, false) ?? attempt(page, true);
@@ -1854,10 +1935,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     pendingSpacing = 0;
                     if (part === 0 && resolved.headings.keepWithNext && run > 0 && run < curCol.blocks.length) {
                         const rolledBack = rollbackTrailingBlocks(curCol, doc.blocks, isFreeHeading);
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         return (rolledBack[0].contentIndex ?? startIdx - rolledBack.length) - 1;
                     }
-                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                    advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                     // 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;
@@ -1893,7 +1974,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 curCol.availableHeight = Math.max(0, curCol.availableHeight - balanceBefore);
             }
             enterBand(startIdx, 0);
-            placeAtomicBlock(placed.frame, placed.totalHeight, spacingBefore, cursor, doc, resolved, contentArea, pageWidthPx, pageHeightPx);
+            placeAtomicBlock(placed.frame, placed.totalHeight, spacingBefore, cursor, doc, geomResolved, contentArea, pageWidthPx, pageHeightPx);
             enterBand(startIdx, 0);
             curCol = currentColumn(doc, cursor);
             commitCallout(placed, startIdx, plan, curCol, part > 0 || fragment ? fragmentRange(L, from, to) : undefined);
@@ -1912,7 +1993,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             from = to;
             part++;
             frameId = `block-${blockIdCounter++}`;
-            advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+            advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
         }
     };
     for (let blockIdx = 0; blockIdx < contentBlocks.length; blockIdx++) {
@@ -1920,6 +2001,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             throw new BuildCancelledError();
         options?.onProgress?.({ pass: 1, blocks: blockIdx, totalBlocks: contentBlocks.length, pages: doc.pages.length });
         const rawBlock = contentBlocks[blockIdx];
+        // The styled section this block sits in: its geometry applies to the
+        // pages opened from here (a heading with `breakBefore` opens one).
+        const blockSection = sectionPlan.byBlock[blockIdx];
+        if (blockSection !== currentSection)
+            enterSection(blockSection);
         // Floats whose reference landed in an earlier iteration take the first
         // free slot of the current page now — after their reference in reading
         // order. Then enqueue the floats first-referenced in this block, so the
@@ -1934,13 +2020,13 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             if (name === 'pagebreak') {
                 pendingSpacing = 0;
                 markForcedBreak();
-                advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                advanceToNextPageBoundary(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx);
                 const parity = attrs.parity;
                 if (parity === 'odd'
                     || parity === 'even'
                     || parity === 'always-odd'
                     || parity === 'always-even') {
-                    enforcePageParity(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, parity);
+                    enforcePageParity(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, parity);
                 }
                 // Pending floats land on the page that follows the break — after
                 // parity padding, so a blank parity page never carries a float.
@@ -1959,7 +2045,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     const page = doc.pages[cursor.pageIndex];
                     if (cursor.columnIndex === page.columns.length - 1)
                         markForcedBreak();
-                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                    advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                     flushPendingNumberingAtBoundary();
                 }
             }
@@ -1975,6 +2061,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 }
                 if (Object.keys(change).length > 0)
                     pendingNumberingChange = change;
+                // A page opened just before (a `:::pagebreak`, the chapter's head)
+                // is still empty: it takes the change now. Otherwise the change
+                // waits for the next page boundary.
+                flushPendingNumberingAtBoundary();
             }
             continue;
         }
@@ -1997,7 +2087,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 pendingSpacing = 0;
                 closeFlowSegment(blockIdx);
                 leaveCurrentPage();
-                enforcePageParity(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, resolved.parts.breakBefore.parity);
+                enforcePageParity(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, resolved.parts.breakBefore.parity);
                 cursor.columnIndex = 0;
                 // Map the opener's title back to the `title="…"` attribute of the
                 // fence so the editor can place the cursor from a click on the band.
@@ -2034,7 +2124,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             pendingSpacing = 0;
             closeFlowSegment(blockIdx);
             leaveCurrentPage();
-            enforcePageParity(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, parity);
+            enforcePageParity(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, parity);
             flushPendingNumberingAtBoundary();
         }
         if (rawBlock.type === 'containerStart' && rawBlock.containerName === 'callout') {
@@ -2082,14 +2172,14 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         }
         // --- Heading `breakBefore` ----------------------------------------
         if (rawBlock.type === 'heading' && rawBlock.level) {
-            const level = headingLevelByNumber.get(rawBlock.level);
+            const level = headingLevels.forBlock(rawBlock);
             const bb = level?.breakBefore;
             if (bb && bb.enabled) {
                 pendingSpacing = 0;
                 closeFlowSegment(blockIdx);
-                advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                advanceToNextPageBoundary(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx);
                 if (bb.parity !== 'any') {
-                    enforcePageParity(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, bb.parity);
+                    enforcePageParity(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, bb.parity);
                 }
                 flushPendingNumberingAtBoundary();
             }
@@ -2100,7 +2190,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             if (level?.span === 'page') {
                 pendingSpacing = 0;
                 closeFlowSegment(blockIdx);
-                advanceToNextPageBoundary(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx);
+                advanceToNextPageBoundary(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx);
                 cursor.columnIndex = 0;
                 flushPendingNumberingAtBoundary();
             }
@@ -2117,7 +2207,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         // Measure against the current column width. `null` means there is nothing
         // to place inline (empty text, unknown resource id, floated resource).
         const col = currentColumn(doc, cursor);
-        const blockMeasureCtx = partPlan.byBlock[blockIdx] ? partMeasureCtx : measureCtx;
+        const blockMeasureCtx = partPlan.byBlock[blockIdx] ? partMeasureCtx : sectionMeasureCtx(sectionPlan.byBlock[blockIdx]);
         const styleOverride = paragraphContainer
             ? (isContainerTail ? paragraphContainer.tailStyle : paragraphContainer.style)
             : undefined;
@@ -2151,6 +2241,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             const groupHeight = measured.totalHeight;
             const blk = createVDTBlock(id, 'resource', style.fontString, style.color, style.textAlign);
             blk.contentIndex = blockIdx;
+            stampBlockExtras(blk, rawBlock);
             blk.resourceBlock = resourceBlock;
             blk.dirty = false;
             blk.snappedToGrid = false;
@@ -2168,7 +2259,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 }];
             const spacingBefore = pendingSpacing;
             enterBand(blockIdx, 0);
-            placeAtomicBlock(blk, groupHeight, spacingBefore, cursor, doc, resolved, contentArea, pageWidthPx, pageHeightPx);
+            placeAtomicBlock(blk, groupHeight, spacingBefore, cursor, doc, geomResolved, contentArea, pageWidthPx, pageHeightPx);
             enterBand(blockIdx, 0);
             // `placeBlockInColumn` (inside placeAtomicBlock) shifts `blk.lines`; the
             // resource's own caption/table lines live on `resourceBlock` and must be
@@ -2234,10 +2325,12 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         // paragraph of a `:::paragraphs` container, whose leading and spacing
         // are off-grid by design.
         const nextIsHeading = nextBlock?.type === 'heading';
-        const shouldSnapToGrid = (vdtType === 'heading' && !nextIsHeading) ||
+        // The contents (`:::toc`) keep their own rhythm: an entry set as a list
+        // item is not a list tail to realign the text after it.
+        const shouldSnapToGrid = rawBlock.toc === undefined && ((vdtType === 'heading' && !nextIsHeading) ||
             (vdtType === 'listItem' && !nextIsListItem) ||
             (vdtType === 'paragraph' && isContainerTail) ||
-            vdtType === 'mathDisplay';
+            vdtType === 'mathDisplay');
         // Place block, splitting across columns/pages if needed.
         // List items may split too — orphan/widow protection per-list is gated by
         // `avoidOrphansInLists` / `avoidWidowsInLists`; bullet stays on first part.
@@ -2290,6 +2383,12 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         spacingBefore = Math.max(spacingBefore, style.marginTopPx);
                     }
                 }
+                else if (rawBlock.toc) {
+                    // A part row or an unnumbered entry of the contents: its top
+                    // margin (`toc.parts.marginTop`, the level's `marginTop`) applies
+                    // like a heading's.
+                    spacingBefore = Math.max(spacingBefore, style.marginTopPx);
+                }
                 // Column balancing: extra grid lines above a non-heading balance
                 // target — the first block after a list end. Heading targets are
                 // handled inside the heading branch above (after margin collapsing).
@@ -2328,7 +2427,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             // subsequent marginBottom + grid snap) starts from there.
             let effectiveRemainHeight = totalRemainHeight;
             if (vdtType === 'heading' && headingLevel !== undefined && partIndex === 0) {
-                const lvl = headingLevelByNumber.get(headingLevel);
+                const lvl = headingLevels.forBlock(rawBlock);
                 if (lvl) {
                     const full = remainingLines
                         .map((ln) => (ln.segments ?? []).map((s) => s.text).join(''))
@@ -2382,6 +2481,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         if (letterSpacingPx !== undefined)
                             blk.letterSpacing = letterSpacingPx;
                         blk.contentIndex = blockIdx;
+                        stampBlockExtras(blk, rawBlock);
                         blk.headingLevel = headingLevel;
                         if (numberPrefix)
                             blk.numberPrefix = numberPrefix;
@@ -2397,7 +2497,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         remainingLines = remainingLines.slice(splitAt);
                         partIndex++;
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         continue;
                     }
                     // Can't cleanly split the colon line off — would create a widow.
@@ -2429,12 +2529,12 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                         // rolled-back heading (marker blocks in between are replayed).
                         blockIdx = (popped[0].contentIndex ?? blockIdx - headingRunCount) - 1;
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         break;
                     }
                     if (headingRunCount === 0) {
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         continue;
                     }
                     // headingRunCount === curCol.blocks.length: fall through to place.
@@ -2490,11 +2590,11 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                             // rolled-back heading (marker blocks in between are replayed).
                             blockIdx = (rolledBack[0].contentIndex ?? blockIdx - rolledBack.length) - 1;
                             pendingSpacing = 0;
-                            advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                            advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                             break;
                         }
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         continue;
                     }
                 }
@@ -2508,6 +2608,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 if (letterSpacingPx !== undefined)
                     blk.letterSpacing = letterSpacingPx;
                 blk.contentIndex = blockIdx;
+                stampBlockExtras(blk, rawBlock);
                 if (partIndex === 0) {
                     blk.headingLevel = headingLevel;
                     if (numberPrefix)
@@ -2573,7 +2674,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                 // other column on this page so body text under the opener band
                 // starts below it in ALL columns, not just the one it was placed in.
                 if (vdtType === 'heading' && headingLevel !== undefined) {
-                    const lvl = headingLevelByNumber.get(headingLevel);
+                    const lvl = headingLevels.forBlock(rawBlock);
                     if (lvl?.span === 'page') {
                         const page = doc.pages[cursor.pageIndex];
                         for (const otherCol of page.columns) {
@@ -2633,6 +2734,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     if (letterSpacingPx !== undefined)
                         blk.letterSpacing = letterSpacingPx;
                     blk.contentIndex = blockIdx;
+                    stampBlockExtras(blk, rawBlock);
                     if (partIndex === 0) {
                         blk.headingLevel = headingLevel;
                         if (numberPrefix)
@@ -2654,7 +2756,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     remainingLines = remainingLines.slice(choice.splitAt);
                     partIndex++;
                     pendingSpacing = 0;
-                    advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                    advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                     continue;
                 }
                 // choice.splitAt === 0: fall through to push whole paragraph to next column
@@ -2679,12 +2781,12 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     if (rolledBack.length > 0) {
                         blockIdx = (rolledBack[0].contentIndex ?? blockIdx - rolledBack.length) - 1;
                         pendingSpacing = 0;
-                        advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                         break;
                     }
                 }
                 pendingSpacing = 0;
-                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                 continue;
             }
             // Empty column with less than a line of room (a band cap cutting right
@@ -2692,7 +2794,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             // go here — move on. The next column, or a fresh page, has room.
             if (curCol.availableHeight < style.lineHeightPx - 0.01 && totalRemainHeight > curCol.availableHeight + 0.01) {
                 pendingSpacing = 0;
-                advanceToNextColumn(doc, cursor, resolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
                 continue;
             }
             // Empty column but block still doesn't fit (block taller than page) — place anyway
@@ -2702,6 +2804,7 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
             if (letterSpacingPx !== undefined)
                 blk.letterSpacing = letterSpacingPx;
             blk.contentIndex = blockIdx;
+            stampBlockExtras(blk, rawBlock);
             if (partIndex === 0)
                 blk.headingLevel = headingLevel;
             if (partIndex === 0 && vdtType === 'heading' && rawBlock.attrs)
@@ -2750,12 +2853,43 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
         page.pageLabel = info.label;
         page.pageNumberFormat = info.format;
     }
-    buildHeadersAndFooters(doc);
+    const restarts = pageNumberSegments
+        .filter((s, i) => i > 0 && s.startAt !== undefined && s.startPageIndex < doc.pages.length)
+        .map((s) => s.startPageIndex);
+    if (restarts.length > 0)
+        doc.pageNumberRestarts = restarts;
+    buildHeadersAndFooters(doc, resourceById);
     doc.converged = true;
     doc.iterationCount = 1;
     return { doc, forcedBreakPages, bandCapProposals, spanPlacedInBand, bandCapsApplied, looseOutcome };
 }
+/** Passes a document printing its own contents gets at most, beyond the
+ *  first, for the page labels it prints to settle. */
+const MAX_TOC_ROUNDS = 3;
 export function buildDocument(content, config, cache, options) {
+    // A document printing its own table of contents (`:::toc` with no
+    // host-supplied outline) is laid out with the page labels of the previous
+    // build until they no longer change: the contents' own length moves what
+    // follows, and a numbering restart after the front matter usually settles
+    // it in one extra round.
+    if (content.outline === undefined) {
+        const parsed = parseMarkdownMemo(extractFrontmatter(content.markdown).content);
+        if (hasTocDirective(parsed)) {
+            let outline = computeOutline(parsed, resolveAllConfig(config), content.continuation?.headings);
+            let doc = buildDocumentBalanced({ ...content, outline }, config, cache, options);
+            for (let round = 0; round < MAX_TOC_ROUNDS; round++) {
+                const after = outlineFromDoc(doc, outline);
+                if (sameOutline(after, outline))
+                    break;
+                outline = after;
+                doc = buildDocumentBalanced({ ...content, outline }, config, cache, options);
+            }
+            return doc;
+        }
+    }
+    return buildDocumentBalanced(content, config, cache, options);
+}
+function buildDocumentBalanced(content, config, cache, options) {
     // Each pass reports its own progress, numbered in build order.
     let passIndex = 0;
     const onProgress = options?.onProgress;
@@ -2776,72 +2910,209 @@ export function buildDocument(content, config, cache, options) {
     const bandCaps = bands.bandCaps;
     let passCount = bands.passCount;
     best.doc.iterationCount = passCount;
-    /** Hints that produced `best` (replayed by the trailing-cap passes). */
-    let bestHints = { bandCaps };
     // --- Column balancing (vertical justification) ------------------------
     // Iteratively re-place the document with extra grid lines above headings
-    // until every balanceable column ends flush with the page bottom (or no
-    // further adjustment is possible). Each retry recomputes the remaining
-    // gaps on the freshly placed document, so split/keep-with-next decisions
-    // that shift under the new spacing are accounted for. The best layout
-    // (fewest leftover gap lines) always wins — a retry that regresses is
-    // discarded.
+    // (and the other levers) until every balanceable column ends flush with
+    // the page bottom, or no further adjustment is possible. Each retry
+    // recomputes the remaining gaps on the freshly placed document, so
+    // split / keep-with-next decisions that shift under the new spacing are
+    // accounted for. The best layout (fewest leftover gap lines) always wins
+    // — a retry that regresses is discarded.
+    //
+    // The pages between explicit breaks (chapter openers, `:::pagebreak`)
+    // are laid out independently of one another — nothing flows across such
+    // a break, so a lever inside one run of pages cannot move a line of any
+    // other. The loop therefore judges every run (a *segment*, see
+    // `pageSegments`) on its own: a pass places the whole document, but each
+    // segment keeps or rejects its share of the levers by its own score,
+    // blacklists its own cascades, plateaus on its own and spends its own
+    // budget of attempts; a rejected segment gets its pages back from the
+    // best pass it had (`spliceSegments`). A book of thirty chapters thus
+    // balances exactly as its chapters would one by one, instead of one
+    // cascade anywhere costing every page of the book a pass.
     const balancing = best.doc.config.headings.balancing;
     if (!balancing.enabled)
         return best.doc;
-    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;
+    /** Levers accepted so far, over every segment (keyed by content index /
+     *  `balanceKey`; each key belongs to exactly one segment). */
+    const applied = { lines: new Map(), loose: new Map() };
+    let segments = [];
+    /** (Re)derive the segments of the current best layout, keeping the
+     *  attempts and blacklists of the segment at the same position. */
+    const resetSegments = () => {
+        const gaps = collectColumnGaps(best.doc, best.forcedBreakPages);
+        const prev = segments;
+        segments = pageSegments(best.doc.pages.length, best.forcedBreakPages).map((range, i) => {
+            const score = gapLinesIn(gaps, range);
+            const old = prev[i];
+            return {
+                range,
+                bestScore: score,
+                attempts: old?.attempts ?? 0,
+                done: score === 0,
+                stable: score === 0,
+                failedLoose: old?.failedLoose ?? new Set(),
+                failedLines: old?.failedLines ?? new Set(),
+            };
+        });
+    };
+    const hintsFrom = (lines, loose, looseBudget) => {
+        const extraPx = new Map();
+        for (const [idx, n] of lines)
+            if (n > 0)
+                extraPx.set(idx, n * best.doc.baselineGrid);
+        return {
+            balanceExtraPx: extraPx,
+            balanceLooseness: loose,
+            ...(looseBudget ? { balanceLooseBudget: looseBudget } : {}),
+            bandCaps,
+        };
+    };
+    const segmentAt = (pageIndex) => segments.findIndex((s) => pageIndex >= s.range.from && pageIndex <= s.range.to);
+    /** Segment owning each lever key of the current best layout. */
+    const keyOwners = (gaps) => {
+        const owner = new Map();
+        for (const g of gaps) {
+            const si = segmentAt(g.pageIndex);
+            if (si < 0)
+                continue;
+            for (const c of g.candidates)
+                owner.set(balanceKey(c.contentIndex, c.part ?? 0), si);
+        }
+        return owner;
+    };
+    /** First page each content index was placed on. */
+    const pageOfContent = (doc) => {
+        const m = new Map();
+        for (const b of doc.blocks) {
+            if (b.contentIndex !== undefined && b.pageIndex !== undefined && !m.has(b.contentIndex))
+                m.set(b.contentIndex, b.pageIndex);
+        }
+        return m;
+    };
+    const inRange = (r, p) => p !== undefined && p >= r.from && p <= r.to;
+    /** Whether the explicit breaks before / around a segment fell on the same
+     *  pages in `next` as in the best layout — the segment's pages then line
+     *  up and can be compared or spliced. `before` checks only the pages
+     *  ahead of it (an earlier segment's cascade shifts everything after). */
+    const breaksMatch = (next, upTo) => {
+        for (let p = 0; p < upTo; p++) {
+            if (best.forcedBreakPages.has(p) !== next.forcedBreakPages.has(p))
+                return false;
+        }
+        return true;
+    };
+    const startIntact = (next, s) => breaksMatch(next, s.range.from);
+    const wholeIntact = (next, s, last) => {
+        if (!breaksMatch(next, s.range.to + 1))
+            return false;
+        if (next.doc.pages.length <= s.range.to)
+            return false;
+        return !last || next.doc.pages.length === best.doc.pages.length;
+    };
+    /**
+     * The best layout with the pages of `ranges` taken from `next` (whose
+     * breaks line up with it there): pages, the blocks and warnings on them,
+     * and the pass report entries whose block sits on them.
+     */
+    const spliceSegments = (next, ranges) => {
+        const taken = (p) => ranges.some((r) => inRange(r, p));
+        const pages = best.doc.pages.map((pg, i) => (taken(i) ? next.doc.pages[i] : pg));
+        const blocks = [
+            ...best.doc.blocks.filter((b) => !taken(b.pageIndex)),
+            ...next.doc.blocks.filter((b) => taken(b.pageIndex)),
+        ].sort((a, b) => (a.pageIndex ?? -1) - (b.pageIndex ?? -1));
+        const warnings = [
+            ...(best.doc.warnings ?? []).filter((w) => !taken(w.pageIndex)),
+            ...(next.doc.warnings ?? []).filter((w) => taken(w.pageIndex)),
+        ].sort((a, b) => a.pageIndex - b.pageIndex);
+        const doc = { ...best.doc, pages, blocks, ...(warnings.length > 0 ? { warnings } : { warnings: undefined }) };
+        const pageBest = pageOfContent(best.doc);
+        const pageNext = pageOfContent(next.doc);
+        const mergeMap = (a, b) => {
+            const out = new Map();
+            for (const [k, v] of a)
+                if (!taken(pageBest.get(k)))
+                    out.set(k, v);
+            for (const [k, v] of b)
+                if (taken(pageNext.get(k)))
+                    out.set(k, v);
+            return out;
+        };
+        const mergeSet = (a, b) => {
+            const out = new Set();
+            for (const k of a)
+                if (!taken(pageBest.get(k)))
+                    out.add(k);
+            for (const k of b)
+                if (taken(pageNext.get(k)))
+                    out.add(k);
+            return out;
+        };
+        return {
+            doc,
+            forcedBreakPages: best.forcedBreakPages,
+            bandCapProposals: mergeMap(best.bandCapProposals, next.bandCapProposals),
+            spanPlacedInBand: mergeSet(best.spanPlacedInBand, next.spanPlacedInBand),
+            bandCapsApplied: mergeSet(best.bandCapsApplied, next.bandCapsApplied),
+            looseOutcome: mergeMap(best.looseOutcome, next.looseOutcome),
+        };
+    };
     /**
-     * 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.
+     * A rejected segment moved content across a column break somewhere in
+     * its pages (a split paragraph whose head no longer fits, a float that
+     * lost its slot, a lead-in that left with its list…): the pages after
+     * that point re-flow, 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 of the segment whose content changed and blacklist
+     * the levers this pass newly applied there (failing that, on its page;
+     * failing that, in the whole segment), 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);
+    const containCascade = (next, s, newLines, newLoose, gaps) => {
+        const div = firstDivergentColumn(best.doc, next.doc, s.range);
         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);
+                    s.failedLines.add(k);
                     hit = true;
                 }
             for (const k of newLoose)
                 if (!cands || cands.has(k)) {
-                    failedLoose.add(k);
+                    s.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)))
+        const keysOf = (pick) => new Set(gaps.filter(pick).flatMap((g) => g.candidates.map((c) => balanceKey(c.contentIndex, c.part ?? 0))));
+        if (blacklist(keysOf((g) => g.pageIndex === div.pageIndex && g.columnIndex === div.columnIndex)))
             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)))
+        if (blacklist(keysOf((g) => g.pageIndex === div.pageIndex)))
             return true;
         return blacklist(null);
     };
+    let balancingPasses = 0;
     const balance = () => {
-        while (!converged && passCount < MAX_BALANCING_PASSES) {
+        while (balancingPasses < MAX_BALANCING_PASSES_PER_DOCUMENT) {
+            const active = segments.filter((s) => !s.done);
+            if (active.length === 0)
+                break;
+            const gaps = collectColumnGaps(best.doc, best.forcedBreakPages);
+            const owner = keyOwners(gaps);
+            const failedLoose = new Set();
+            const failedLines = new Set();
+            for (const s of segments) {
+                for (const k of s.failedLoose)
+                    failedLoose.add(k);
+                for (const k of s.failedLines)
+                    failedLines.add(k);
+            }
             const proposal = proposeBalanceLines(best.doc, best.forcedBreakPages, applied, {
                 maxLinesPerHeading: balancing.maxLinesPerHeading,
                 stretchAfterLists: balancing.stretchAfterLists,
@@ -2854,67 +3125,114 @@ export function buildDocument(content, config, cache, options) {
                 failedLoose,
                 failedLines,
             });
-            if (!proposal.changed) {
+            // The levers newly proposed, by segment; those of a segment that is
+            // done (plateaued, out of attempts) are withdrawn from the pass.
+            const newLines = [];
+            const newLoose = [];
+            for (const [k, n] of proposal.lines) {
+                const cur = applied.lines.get(k) ?? 0;
+                if (n <= cur)
+                    continue;
+                const si = owner.get(k);
+                if (si === undefined || segments[si].done) {
+                    if (cur > 0)
+                        proposal.lines.set(k, cur);
+                    else
+                        proposal.lines.delete(k);
+                    continue;
+                }
+                newLines.push(k);
+            }
+            for (const k of [...proposal.loose.keys()]) {
+                if (applied.loose.has(k))
+                    continue;
+                const si = owner.get(k);
+                if (si === undefined || segments[si].done) {
+                    proposal.loose.delete(k);
+                    proposal.looseBudget.delete(k);
+                    continue;
+                }
+                newLoose.push(k);
+            }
+            const trying = new Set([...newLines, ...newLoose].map((k) => owner.get(k)));
+            if (trying.size === 0) {
                 // No stretch point can absorb the remaining gaps — stable.
-                converged = true;
+                for (const s of active) {
+                    s.done = true;
+                    s.stable = true;
+                }
                 break;
             }
-            const extraPx = new Map();
-            for (const [idx, n] of proposal.lines)
-                extraPx.set(idx, n * best.doc.baselineGrid);
-            const hints = {
-                balanceExtraPx: extraPx,
-                balanceLooseness: proposal.loose,
-                balanceLooseBudget: proposal.looseBudget,
-                bandCaps,
-            };
-            const next = runPass(hints);
+            for (const si of trying)
+                segments[si].attempts++;
+            const next = runPass(hintsFrom(proposal.lines, proposal.loose, proposal.looseBudget));
             passCount++;
-            // Band caps ride along unchanged; a retry that unsettles one (its span
-            // block no longer lands in the capped band, or a levelled closing band
-            // spills past its cut) counts as a regression — capped columns without
-            // their box are not a layout we may keep.
-            const capsDelivered = [...bandCaps.keys()].every((i) => next.spanPlacedInBand.has(i));
-            const score = capsDelivered ? totalGapLines(next.doc, next.forcedBreakPages) : Infinity;
-            // Loose paragraphs that gained no line at any tracking rung are
-            // blacklisted whatever the score did, and never counted as applied.
-            // Candidates the pass never tried (their column's budget was met
-            // first) stay eligible for a later proposal.
-            const newlyLoose = [...proposal.loose.keys()].filter((k) => !applied.loose.has(k));
-            const looseFailed = newlyLoose.filter((k) => next.looseOutcome.get(k) === null);
-            for (const k of looseFailed)
-                failedLoose.add(k);
-            const looseWon = newlyLoose.filter((k) => typeof next.looseOutcome.get(k) === 'number');
-            if (score < bestScore) {
-                best = next;
-                bestHints = hints;
-                bestScore = score;
-                applied = {
-                    lines: proposal.lines,
-                    loose: new Map([...proposal.loose].filter(([k]) => applied.loose.has(k) || looseWon.includes(k))),
-                };
-                converged = score === 0;
-            }
-            else {
-                // 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))
+            balancingPasses++;
+            const nextGaps = collectColumnGaps(next.doc, next.forcedBreakPages);
+            const capPage = pageOfContent(best.doc);
+            const accepted = [];
+            for (const si of trying) {
+                const s = segments[si];
+                // An earlier segment's cascade shifted this one's pages: the pass
+                // says nothing about its levers. They are offered again once the
+                // culprit is blacklisted.
+                if (!startIntact(next, s)) {
+                    s.attempts--;
                     continue;
-                if (looseFailed.length > 0 || looseWon.length > 0) {
+                }
+                const keysLines = newLines.filter((k) => owner.get(k) === si);
+                const keysLoose = newLoose.filter((k) => owner.get(k) === si);
+                // Band caps ride along unchanged; a retry that unsettles one of the
+                // segment's (its span block no longer lands in the capped band, or
+                // a levelled closing band spills past its cut) is a regression —
+                // capped columns without their box are not a layout we may keep.
+                const capsDelivered = [...bandCaps.keys()].every((i) => !inRange(s.range, capPage.get(i)) || next.spanPlacedInBand.has(i));
+                const score = capsDelivered && wholeIntact(next, s, si === segments.length - 1)
+                    ? gapLinesIn(nextGaps, s.range)
+                    : Infinity;
+                // Loose paragraphs that gained no line at any tracking rung are
+                // blacklisted whatever the score did, and never counted as applied.
+                // Candidates the pass never tried (their column's budget was met
+                // first) stay eligible for a later proposal.
+                const looseFailed = keysLoose.filter((k) => next.looseOutcome.get(k) === null);
+                for (const k of looseFailed)
+                    s.failedLoose.add(k);
+                const looseWon = keysLoose.filter((k) => typeof next.looseOutcome.get(k) === 'number');
+                if (score < s.bestScore) {
+                    for (const k of keysLines)
+                        applied.lines.set(k, proposal.lines.get(k));
                     for (const k of looseWon)
-                        failedLoose.add(k);
-                    continue;
+                        applied.loose.set(k, proposal.loose.get(k));
+                    s.bestScore = score;
+                    if (score === 0) {
+                        s.done = true;
+                        s.stable = true;
+                    }
+                    accepted.push(s.range);
                 }
-                break;
+                else if (!containCascade(next, s, keysLines, keysLoose, gaps)) {
+                    // Plateau or regression without a cascade to contain: 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 segment did not improve (the gain
+                    // landed elsewhere — drop them too). A pure spacing plateau means
+                    // the segment is done: it keeps the best layout found so far.
+                    if (looseFailed.length > 0 || looseWon.length > 0) {
+                        for (const k of looseWon)
+                            s.failedLoose.add(k);
+                    }
+                    else {
+                        s.done = true;
+                    }
+                }
+                if (!s.done && s.attempts >= MAX_BALANCING_PASSES)
+                    s.done = true;
             }
+            if (accepted.length > 0)
+                best = spliceSegments(next, accepted);
         }
     };
+    resetSegments();
     balance();
     // --- Trailing bands (closing columns cut level) -------------------------
     // Once the balancing levers have settled the earlier pages, level the
@@ -2925,20 +3243,19 @@ export function buildDocument(content, config, cache, options) {
     // block and the cap applies. A short polish round then lets the levers
     // fill what the cut left short (a column ending a line under the cap).
     if (balancing.trailing) {
-        const trailing = resolveTrailingCaps(best, bandCaps, (caps) => runPass({ ...bestHints, bandCaps: caps }));
+        const frozen = hintsFrom(applied.lines, applied.loose);
+        const trailing = resolveTrailingCaps(best, bandCaps, (caps) => runPass({ ...frozen, bandCaps: caps }));
         passCount += trailing.passCount;
         if (trailing.result !== best) {
             best = trailing.result;
             for (const [i, cap] of trailing.caps)
                 bandCaps.set(i, cap);
-            bestHints = { ...bestHints, bandCaps };
-            bestScore = totalGapLines(best.doc, best.forcedBreakPages);
-            converged = bestScore === 0;
+            resetSegments();
             balance();
         }
     }
     best.doc.iterationCount = passCount;
-    best.doc.converged = converged || bestScore === 0;
+    best.doc.converged = segments.every((s) => s.stable || s.bestScore === 0);
     return best.doc;
 }
 //# sourceMappingURL=build.js.map