postext 0.3.36 → 0.3.38

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';
@@ -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,61 @@ 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 = raw.toc.pageIndex !== undefined ? { pageIndex: raw.toc.pageIndex } : {};
+        }
+        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 } : {}),
+                ...(raw.toc.pageIndex !== undefined ? { pageIndex: raw.toc.pageIndex } : {}),
+            };
+        }
+    };
     let blockIdCounter = 0;
     let pendingSpacing = 0;
     // Pages whose break into the next page is explicit rather than natural
@@ -1029,11 +1103,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,
@@ -1047,20 +1121,34 @@ 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. */
+    /** The earliest page a pending change may number: the page the directive
+     *  was met on while still empty, else the page after it. */
+    let pendingNumberingPage = 0;
+    /** A page holding something the reader sees: column content, a float, a
+     *  part opener. A parity blank is not one. */
+    const pageTakesNumbering = (page) => pageHasContent(page) || (page.floats?.length ?? 0) > 0 || page.partInfo !== undefined;
+    /** Commits a pending `:::numbering` change to the first page from the
+     *  directive on that receives content: the page the directive opens (the
+     *  head of a chapter, right after a page break) or, when that page was
+     *  already written on, the next one — never a blank page padding parity
+     *  in between. Called after every block iteration and page advance. */
     const flushPendingNumberingAtBoundary = () => {
-        if (cursor.pageIndex > lastSeenPageIndex) {
-            if (pendingNumberingChange) {
-                pageNumberSegments.push({
-                    startPageIndex: cursor.pageIndex,
-                    ...pendingNumberingChange,
-                });
-                pendingNumberingChange = null;
-            }
-            lastSeenPageIndex = cursor.pageIndex;
-        }
+        if (!pendingNumberingChange)
+            return;
+        if (cursor.pageIndex < pendingNumberingPage)
+            return;
+        const page = doc.pages[cursor.pageIndex];
+        if (!pageTakesNumbering(page))
+            return;
+        // 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;
     };
     /** 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 +1596,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 +1668,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 +1698,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 +1804,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 +1942,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 +1981,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 +2000,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 +2008,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 +2027,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 +2052,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();
                 }
             }
@@ -1973,8 +2066,10 @@ export function buildDocumentPass(content, config, cache, options, hints = {}) {
                     if (Number.isInteger(n) && n >= 1)
                         change.startAt = n;
                 }
-                if (Object.keys(change).length > 0)
+                if (Object.keys(change).length > 0) {
                     pendingNumberingChange = change;
+                    pendingNumberingPage = pageTakesNumbering(doc.pages[cursor.pageIndex]) ? cursor.pageIndex + 1 : cursor.pageIndex;
+                }
             }
             continue;
         }
@@ -1997,7 +2092,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 +2129,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 +2177,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 +2195,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 +2212,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 +2246,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 +2264,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 +2330,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 +2388,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 +2432,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 +2486,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 +2502,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 +2534,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 +2595,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 +2613,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 +2679,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 +2739,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 +2761,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 +2786,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 +2799,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 +2809,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 +2858,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;