postext 1.33.11 → 1.34.1

package/dist/pipeline/build.js

@@ -34,6 +34,9 @@ import { anchorTargetsOf, hasAnchorRefs, printsAnchorPages } from './crossRefs';
 import { applyStatementNumbering, numberStatements, outlineLookup } from './statementNumbering';
 import { SPAN_EMBED_STYLE_ID, isPageSpanStrip, spanEmbedStyle, wrapPageSpanEmbeds } from './spanEmbeds';
 import { flowColumnsStyles, isFlowColumnsStyle, wrapFlowColumns } from './flowColumns';
+import { FRAME_STYLE_ID, frameBoxStyle, wrapComposedPages } from '../composed/wrap';
+import { resolvePageTemplate } from '../composed/templates';
+import { composedPageAt, frameStyleOf, layoutComposedPage, planComposedPages } from './composedLayout';
 import { anchorOutline, computeOutline, hasIndexDirective, hasTocDirective, headingNumberingOptions, headingTemplatesOf, outlineFromDoc, sameOutline } from './outline';
 import { expandTocDirectives } from './toc';
 import { expandIndexDirectives, locateIndexMarks } from './indexDirective';
@@ -49,8 +52,8 @@ import { measureContentBlock } from './measureContentBlock';
 import { containerStyle, paragraphStyleIdOf, planParagraphContainers } from './paragraphContainers';
 import { appendChapterEndNotes, footnoteIdsOfLines, footnoteParagraphStyle, noteContentBlock, noteNumberPositionOf, numberFootnotes, footnoteFormatOf, numberFootnotesByPlacement, sameFootnoteNumbers, splitFootnoteDefinitions, withFootnoteStyle, } from './footnotes';
 import { planParts, derivePartMeasureContext } from './parts';
-import { layoutCallout, offsetBlock, offsetCalloutToAbsolute, pickCalloutStyle, planCallouts, resolveCalloutAttrs, } from './calloutLayout';
-import { fillGalley, galleyBreaks } from './columnsGroup';
+import { offsetBlock, offsetCalloutToAbsolute, pickCalloutStyle, planCallouts, resolveCalloutAttrs, } from './calloutLayout';
+import { CUT_START, fragmentRange, makeCalloutLayouter as makeCalloutLayouterIn, splitCalloutFragment as splitCalloutFragmentIn, tallerThanColumn as tallerThanColumnIn, } from './frameLayout';
 import { chooseTableSlice, layoutCaptionText, layoutResourceBlock, MIN_TAIL_ROWS } from './resourceLayout';
 import { computeFloatPlan, floatedResourceIds, floatColumnCount, resolveResourcePlacement, } from './floatPlacement';
 import { enumerateCurrentPageSlots, measureFloatBand, floatGapAbove, floatGapBelow, measureSideStack, clearSideObstacles, columnHasFloatBand, fitsStrict, trueBottom, } from './floatSlots';
@@ -77,6 +80,7 @@ import { annotateArabicMarks } from '../arabicMarks';
 import { literalBreaksFor } from './hardBreaks';
 import { tashkilFor } from './tashkil';
 import { overlineEmphasis } from '../emphasisOverline';
+import { highlightDocument } from '../highlightMarks';
 import { withBookTitleBrackets } from './annotations';
 import { paperByBlock, stampPagePaper } from './paper';
 import { headingLineSpanBand } from './lineSpan';
@@ -479,7 +483,13 @@ function placeDocumentPass(content, config, cache, options, hints) {
     // set by the span-block path like any other.
     // A `:::columns` group in the running text (#634): each in a frameless
     // box the callout machinery places, cuts and splits.
-    const flowGroups = resolved.layout.flowColumns ? wrapFlowColumns(numberedBlocks) : { blocks: numberedBlocks, wrapped: false };
+    // Composed pages (#855): each page's content regrouped into the stories
+    // its template's frames receive, one frameless box each (set at the
+    // page's template, below). Before the main-flow groups: a `:::columns`
+    // in a frame is a group of its box.
+    const templateSource = { pageTemplates: resolved.pageTemplates, calloutStyles: resolved.calloutStyles };
+    const composedWrap = wrapComposedPages(numberedBlocks, templateSource);
+    const flowGroups = resolved.layout.flowColumns ? wrapFlowColumns(composedWrap.blocks) : { blocks: composedWrap.blocks, wrapped: false };
     const spanEmbeds = wrapPageSpanEmbeds(flowGroups.blocks, content.resources ?? [], effectiveResourceTypes(config, content.resources ?? []));
     // Code listings (#624): each in a box of the code style, which the
     // callout machinery places and splits.
@@ -525,6 +535,8 @@ function placeDocumentPass(content, config, cache, options, hints) {
     const syntheticBoxes = [
         ...(spanEmbeds.wrapped ? [spanEmbedStyle(bodyStyle.lineHeightPx, resolved.layout.inlineResourceGap !== 'above')] : []),
         ...(codeBoxes.wrapped ? [codeBoxStyle(resolved)] : []),
+        // The frameless box of a composed page's story (#855).
+        ...(composedWrap.wrapped ? [frameBoxStyle(Math.max(resolved.bodyText.avoidOrphans ? resolved.bodyText.orphanMinLines : 1, resolved.bodyText.avoidWidows ? resolved.bodyText.widowMinLines : 1))] : []),
         // The boxes of main-flow groups: sub-columns a body line apart in the
         // text column, a gutter apart across the page.
         ...(flowGroups.wrapped
@@ -536,7 +548,7 @@ function placeDocumentPass(content, config, cache, options, hints) {
         : resolved.calloutStyles;
     // A box nested in another looks its style up in the configuration it is
     // laid out with: the listings' box among them.
-    const calloutResolved = codeBoxes.wrapped || flowGroups.wrapped ? { ...resolved, calloutStyles } : resolved;
+    const calloutResolved = codeBoxes.wrapped || flowGroups.wrapped || composedWrap.wrapped ? { ...resolved, calloutStyles } : resolved;
     const blockquoteStyle = resolveBlockquoteStyle(resolved);
     const listLevelIndentsPx = computeLevelIndentsPx(resolved, bodyStyle.fontSizePx);
     const orderedMetrics = computeOrderedListRunMetrics(contentBlocks, resolved, bodyStyle.fontSizePx);
@@ -568,6 +580,23 @@ function placeDocumentPass(content, config, cache, options, hints) {
     // mode of the styled section the reference sits in (a horizontal
     // appendix of a vertical book turns its figures as asked).
     const floatPlan = computeFloatPlan(contentBlocks, resources, resourceTypes, incorporated, (blockIdx) => sectionWritingMode(sectionPlan, resolved, blockIdx) === 'vertical-rl', resolved.layout.floatShrink, resolved.layout.wrap, resolved.layout.floatsAtCitingPage);
+    // A composed page's pictures are set in its frames: a `::resource` a
+    // story holds does not float. A reference in a frame to a picture set
+    // elsewhere floats from the page's end, to the pages after it.
+    const composedPlans = planComposedPages(contentBlocks, calloutPlan, templateSource);
+    if (composedPlans.size > 0) {
+        for (let k = floatPlan.length - 1; k >= 0; k--) {
+            const f = floatPlan[k];
+            const page = composedPageAt(composedPlans, f.firstBlockIdx);
+            if (!page)
+                continue;
+            const raw = contentBlocks[f.firstBlockIdx];
+            if (raw?.type === 'resourceBlock' && raw.resourceId === f.resourceId && page.storyAt(f.firstBlockIdx))
+                floatPlan.splice(k, 1);
+            else
+                f.firstBlockIdx = page.endIdx;
+        }
+    }
     const floatedIds = floatedResourceIds(floatPlan, incorporated, resources, resourceTypes);
     const floatsByFirstBlock = new Map();
     for (const f of floatPlan) {
@@ -2986,7 +3015,7 @@ function placeDocumentPass(content, config, cache, options, hints) {
         // 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 && !page.comic && cursor.columnIndex === 0
+        if (page && !page.partInfo && !page.comic && !page.composed && cursor.columnIndex === 0
             && !pageHasContent(page) && !(page.floats && page.floats.length > 0)) {
             const fresh = createPageWithColumns(page.index, geomResolved, contentArea, pageWidthPx, pageHeightPx, pageIndexOffset);
             if (page.blankForParity)
@@ -3033,11 +3062,13 @@ function placeDocumentPass(content, config, cache, options, hints) {
         // one in an Arabic book. Its lines carry their span (`VDTLine.measure`).
         if (blk.type !== 'resource' && raw.direction !== undefined && raw.direction !== resolvedDirection(resolved))
             blk.direction = raw.direction;
+        const tocContinued = raw.toc?.group?.role === 'continuation' ? { continued: true } : {};
         if (raw.toc?.kind === 'entry') {
-            blk.tocEntry = raw.toc.pageIndex !== undefined ? { pageIndex: raw.toc.pageIndex } : {};
+            blk.tocEntry = { ...(raw.toc.pageIndex !== undefined ? { pageIndex: raw.toc.pageIndex } : {}), ...tocContinued };
         }
         if (raw.toc?.kind === 'part') {
             blk.tocPart = {
+                ...tocContinued,
                 number: raw.toc.number,
                 title: raw.toc.title ?? '',
                 pageLabel: raw.toc.pageLabel ?? '',
@@ -3366,7 +3397,7 @@ function placeDocumentPass(content, config, cache, options, hints) {
      */
     const openSpanHeadingHere = (blockIdx, rawBlock, level) => {
         const page = doc.pages[cursor.pageIndex];
-        if (page.partInfo || page.comic || currentColumn(doc, cursor).kind === 'span')
+        if (page.partInfo || page.comic || page.composed || currentColumn(doc, cursor).kind === 'span')
             return false;
         const band = currentBand(page, cursor);
         const cols = bandColumns(page, band);
@@ -3500,7 +3531,7 @@ function placeDocumentPass(content, config, cache, options, hints) {
         if (!balancingCfg.enabled || !balancingCfg.trailing)
             return;
         const page = doc.pages[cursor.pageIndex];
-        if (page.columns[cursor.columnIndex]?.kind === 'span' || page.partInfo || page.comic)
+        if (page.columns[cursor.columnIndex]?.kind === 'span' || page.partInfo || page.comic || page.composed)
             return;
         const band = currentBand(page, cursor);
         const cols = bandColumns(page, band).filter((c) => c.bbox.height > 0.5);
@@ -3706,6 +3737,12 @@ function placeDocumentPass(content, config, cache, options, hints) {
     /** A closed `:::paper` still owes a page break before the next placed
      *  block. */
     let pendingPaperBreak = false;
+    /** A composed page (`::::page`, #854) owes a page break before the next
+     *  placed block: `'page'` once its template was laid on the current page
+     *  (nothing flowed on it), `'flow'` after content set in the flow (a page
+     *  of unknown template, or what no frame took), which closes as a
+     *  `:::paper` run does. */
+    let pendingComposedBreak = false;
     /** A comic page (`:::page`) was laid out on the current page: the next
      *  placed block opens a new one (a page that ends the document leaves no
      *  empty page behind). */
@@ -3735,7 +3772,7 @@ function placeDocumentPass(content, config, cache, options, hints) {
     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 || page.comic !== undefined;
+    const pageTakesNumbering = (page) => pageHasContent(page) || (page.floats?.length ?? 0) > 0 || page.partInfo !== undefined || page.comic !== undefined || page.composed !== 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
@@ -3900,16 +3937,14 @@ function placeDocumentPass(content, config, cache, options, hints) {
             doc.blocks.push(child);
         }
     };
-    /** The widths a child's lines are counted at in a fragment `width` wide
-     *  that opens `from` (see `CalloutCut.widths`). */
-    const cutWidths = (from, width) => {
-        const before = from.line > 0 ? from.widths : undefined;
-        if (!before || before.length === 0)
-            return [{ fromLine: 0, width }];
-        const last = before[before.length - 1];
-        return Math.abs(last.width - width) <= 0.5 ? before : [...before, { fromLine: from.line, width }];
-    };
-    const CUT_START = { child: 0, line: 0 };
+    // --- Callout fragments (`keepTogether: false`) ---------------------------
+    // A splittable box breaks only BETWEEN its child blocks (a list item or a
+    // paragraph is never cut in two): the fragment that fits closes the
+    // current column / page, the rest continues in a box of its own — same
+    // frame, stripe and marker, no title or icon — on the next one, and may
+    // split again. Every
+    // fragment's frame shares the fence's `contentIndex` / `containerId` and
+    // records its `callout.part` / `callout.continued`.
     /** A strip in a box (the box of a page-wide strip set `here`, #590):
      *  laid out at the box's inner width, as tall as a page allows, with its
      *  placeholder line; the page it lays out for is the cursor's. */
@@ -3920,85 +3955,21 @@ function placeDocumentPass(content, config, cache, options, hints) {
         withStripPlaceholder(blk, stripGeometry(idx, raw.comic, width, contentArea.height - 2 * floatGapPx, pageIsVertical(doc.pages[cursor.pageIndex])));
         return blk;
     };
-    const makeCalloutLayouter = (startIdx, plan, style) => {
-        const children = contentBlocks.slice(startIdx + 1, plan.endIdx);
-        const realAt = [];
-        children.forEach((c, k) => {
-            if ((c.type !== 'directive' || (c.directiveName === 'strip' && c.comic)) && !isMarkerBlock(c))
-                realAt.push(k);
-        });
-        // `:::columns` groups among the children, as [start marker, end marker]
-        // positions: a split never cuts inside one.
-        const groups = [];
-        children.forEach((c, k) => {
-            if (c.type === 'containerStart' && c.containerName === 'columns') {
-                let e = k + 1;
-                while (e < children.length && !(children[e].type === 'containerEnd' && children[e].containerName === 'columns' && children[e].containerId === c.containerId))
-                    e++;
-                groups.push([k, e]);
-            }
-        });
-        const layoutRange = (from, to, width, frameId, continuation, mirrored = false) => {
-            let n = 0;
-            // A fragment that opens inside a `:::columns` group starts at its
-            // opening marker and one that ends inside it at its closing marker:
-            // the group sets the part between the cut's positions (#634).
-            const fromChild = from.group ? from.group.open : from.child;
-            const closeOfGroup = (open) => groups.find(([gs]) => gs === open)?.[1] ?? children.length - 1;
-            // A cut inside child `to.child` includes that child (its first
-            // `to.line` lines); a cut at a child's head excludes it.
-            const toChild = to.group ? closeOfGroup(to.group.open) + 1 : to.line > 0 ? to.child + 1 : to.child;
-            const inSlice = (pos) => pos.map((p) => ({ ...p, child: p.child - fromChild }));
-            // Nested boxes still open at `from` (their closing markers leading
-            // the range close them): the fragment opens inside them.
-            const open = [];
-            for (let k = 0; k < fromChild; k++) {
-                const c = children[k];
-                if (c.containerName !== 'callout')
-                    continue;
-                if (c.type === 'containerStart')
-                    open.push({ idx: startIdx + 1 + k, block: c });
-                else if (c.type === 'containerEnd')
-                    open.pop();
-            }
-            for (let k = fromChild; k < children.length && open.length > 0; k++) {
-                const c = children[k];
-                if (c.type !== 'containerEnd' || c.containerId !== open[open.length - 1].block.containerId)
-                    break;
-                open.pop();
-            }
-            return layoutCallout({
-                style,
-                attrs: plan.attrs,
-                ...(contentBlocks[startIdx]?.direction ? { direction: contentBlocks[startIdx].direction } : {}),
-                continuation,
-                // Any range short of the box's end is a fragment that goes on.
-                ...(to.child < children.length || to.line > 0 || to.group ? { continues: true } : {}),
-                children: children.slice(fromChild, toChild),
-                childStartIdx: startIdx + 1 + fromChild,
-                width,
-                // A main-flow group's box sets its blocks as the text around it is
-                // set: a styled section's or a part's body (#634).
-                ctx: isFlowColumnsStyle(style.id)
-                    ? (partPlan.byBlock[startIdx] ? partMeasureCtx : sectionMeasureCtx(sectionPlan.byBlock[startIdx]))
-                    : measureCtx,
-                resolved: calloutResolved,
-                containerId: plan.containerId,
-                frameId,
-                nextChildId: () => `${frameId}-c${n++}`,
-                paragraphContainers,
-                ...(from.line > 0 && !from.group ? { lineFrom: from.line } : {}),
-                ...(from.line > 0 && !from.group && from.widths ? { lineWidths: from.widths } : {}),
-                ...(to.line > 0 && !to.group ? { lineTo: to.line } : {}),
-                ...(from.group ? { groupFrom: inSlice(from.group.pos) } : {}),
-                ...(to.group ? { groupTo: inSlice(to.group.pos) } : {}),
-                ...(open.length > 0 ? { openNested: open } : {}),
-                mirrored,
-                stripBlock: calloutStripBlock,
-            });
-        };
-        return { children, childBase: startIdx + 1, realAt, end: { child: children.length, line: 0 }, layoutRange, groups };
-    };
+    /** What the box typesetter (`frameLayout.ts`) reads of this pass. */
+    const framePass = {
+        contentBlocks,
+        resolved,
+        calloutResolved,
+        paragraphContainers,
+        // A main-flow group's box sets its blocks as the text around it is
+        // set: a styled section's or a part's body (#634).
+        measureCtxFor: (startIdx, style) => (isFlowColumnsStyle(style.id) || style.id === FRAME_STYLE_ID
+            ? (partPlan.byBlock[startIdx] ? partMeasureCtx : sectionMeasureCtx(sectionPlan.byBlock[startIdx]))
+            : measureCtx),
+        stripBlock: calloutStripBlock,
+        columnHeight: () => contentArea.height,
+    };
+    const makeCalloutLayouter = (startIdx, plan, style) => makeCalloutLayouterIn(framePass, startIdx, plan, style);
     /** Whether a page swaps its mirrored margins (a verso of a left-bound
      *  book, a recto of a right-bound one: an `'outer'` corner icon hangs on
      *  the left there). A vertical page has no outer side: a box's outer
@@ -4024,192 +3995,8 @@ function placeDocumentPass(content, config, cache, options, hints) {
         const withSide = side && sideUsedBottom(side) > side.bbox.y + 0.5 ? [...cols, side] : cols;
         return bandUsedBottom(withSide);
     };
-    /** The longest leading fragment of the box from cut `from` on whose box
-     *  is at most `roomPx` tall. Cuts fall between children or between the
-     *  lines of a text child. `splitMinLines` guards text: a cut between
-     *  children leaves on each side at least that many text lines or at least
-     *  one indivisible block (a figure, table, display formula or nested
-     *  box); a cut inside a text child counts every line on its side, a block
-     *  as one line, and leaves at least `layout.boxChildSplitMinLines` lines
-     *  of that child on each side (two by default, `splitMinLines` when that
-     *  is lower; EF-115). A nested box that may split
-     *  itself (`keepTogether: false`, or taller than a full column) offers the cuts
-     *  inside it too, by its own `splitMinLines` over its own children; the
-     *  fragments on both sides redraw its frame. The full layout's geometry
-     *  ranks the candidates (box bottom = content bottom at the cut + the
-     *  tails of the boxes closed below it); the deepest candidate that fits
-     *  is laid out for real and taken when it truly fits. `null` when none
-     *  does. */
-    const splitCalloutFragment = (L, from, width, roomPx, frameId, continuation, minLines, mirrored = false) => {
-        const full = L.layoutRange(from, L.end, width, frameId, continuation, mirrored);
-        /** Figures, tables and display formulas: never cut, not text lines. */
-        const indivisible = (c) => c.type === 'resource' || c.type === 'mathDisplay';
-        const unitBottom = (u) => {
-            const b = u.kind === 'block' ? u.block.bbox : u.box.result.frame.bbox;
-            return b.y + b.height;
-        };
-        /** Room a box keeps under its last item (padding, border, icon growth). */
-        const tailOf = (r) => {
-            const last = r.units[r.units.length - 1];
-            return last ? r.frame.bbox.y + r.totalHeight - unitBottom(last) : 0;
-        };
-        if (full.units.length === 0)
-            return null;
-        // A head that goes on also carries the style's continuation marker.
-        const tail = tailOf(full) + full.continuesMarkerPx;
-        /** Candidate cuts with the head's content bottom. A `soft` cut parts a
-         *  wrapped code line from its continuation (#624): taken only when no
-         *  other cut fits. */
-        const candidates = [];
-        /** Collect the cuts among `units` (one box's items; `below` = the tails
-         *  of the nested boxes around them), each side of a cut holding enough
-         *  by the box's `min` lines: a block counts as one line, a nested box
-         *  as one indivisible block. */
-        const collect = (units, minLines, below) => {
-            const min = Math.max(1, minLines);
-            const lineCount = (u) => (u.kind === 'block' ? Math.max(1, u.block.lines.length) : 1);
-            const isBlock = (u) => u.kind === 'box' || indivisible(u.block);
-            const totalLines = units.reduce((n, u) => n + lineCount(u), 0);
-            const totalBlocks = units.filter(isBlock).length;
-            /** A side of a cut holds enough: `lines` (blocks included) of which
-             *  `blocks` are indivisible. Between children, one block suffices or
-             *  the text lines alone meet the minimum; inside a text child, the
-             *  lines do. */
-            const holds = (lines, blocks, betweenChildren) => betweenChildren ? blocks > 0 || lines - blocks >= min : lines >= min;
-            const bothHold = (lines, blocks, betweenChildren) => holds(lines, blocks, betweenChildren) && holds(totalLines - lines, totalBlocks - blocks, betweenChildren);
-            let linesBefore = 0;
-            let blocksBefore = 0;
-            units.forEach((u, i) => {
-                let next;
-                if (u.kind === 'block') {
-                    const c = u.block;
-                    const k = (c.contentIndex ?? L.childBase) - L.childBase;
-                    next = k + 1;
-                    if (!indivisible(c) && c.lines.length > 1) {
-                        // The first laid-out child of a continuation opens after
-                        // `from.line` lines: cuts inside it are counted from the
-                        // child's own head. Each side of the box still counts all its
-                        // lines against `min`, and a cut inside a child leaves at least
-                        // `layout.boxChildSplitMinLines` lines of it on each side (2 by
-                        // default, so no lone line: EF-115), or `min` when that is
-                        // lower. The count is of this fragment's part of the child,
-                        // since a part left behind already passed the test.
-                        const childMin = Math.min(min, resolved.layout.boxChildSplitMinLines);
-                        const lineBase = k === from.child ? from.line : 0;
-                        for (let l = childMin; l <= c.lines.length - childMin; l++) {
-                            const line = c.lines[l - 1];
-                            if (bothHold(linesBefore + l, blocksBefore, false)) {
-                                candidates.push({
-                                    cut: { child: k, line: lineBase + l, widths: k === from.child ? cutWidths(from, width) : [{ fromLine: 0, width }] },
-                                    bottom: line.bbox.y + line.bbox.height + below,
-                                    ...(c.lines[l]?.codeLine?.continued ? { soft: true } : {}),
-                                });
-                            }
-                        }
-                    }
-                }
-                else {
-                    const { box } = u;
-                    if (box.endIdx !== undefined)
-                        next = box.endIdx + 1 - L.childBase;
-                    if (!box.style.keepTogether || tallerThanColumn(box.result)) {
-                        collect(box.result.units, box.style.splitMinLines, below + tailOf(box.result));
-                    }
-                }
-                linesBefore += lineCount(u);
-                if (isBlock(u))
-                    blocksBefore++;
-                if (i < units.length - 1 && next !== undefined && bothHold(linesBefore, blocksBefore, true)) {
-                    candidates.push({ cut: { child: next, line: 0 }, bottom: unitBottom(u) + below });
-                }
-            });
-        };
-        collect(full.units, minLines, 0);
-        // Inside a `:::columns` group of the box (#634): the cut the group
-        // offers for the room, where each of its sub-columns (each stream, in
-        // a parallel group) ends when the galley fills them in turn; at least
-        // one stream goes on and one moves on. A group of a nested box is
-        // never cut, nor any group under 1.24's rules (`layout.flowColumns`).
-        if (resolved.layout.flowColumns) {
-            const base = from.group ? from.group.open : from.child;
-            const childMin = Math.min(Math.max(1, minLines), resolved.layout.boxChildSplitMinLines);
-            for (const g of full.groups ?? []) {
-                const h = roomPx - tail - g.top;
-                if (h <= 0.5)
-                    continue;
-                const reopened = from.group?.open === g.open + base ? from.group : undefined;
-                const pos = [];
-                let moved = false;
-                let left = false;
-                let used = 0;
-                g.streams.forEach((items, s) => {
-                    const end = { child: (g.ends[s] ?? g.close) + base, line: 0 };
-                    if (items.length === 0) {
-                        pos.push(end);
-                        return;
-                    }
-                    const breaks = galleyBreaks(items, childMin);
-                    const fill = fillGalley(items, breaks, g.flow === 'snake' ? g.columns : 1, h);
-                    if (fill.end) {
-                        moved = true;
-                        used = Math.max(used, fill.used);
-                        pos.push(end);
-                        return;
-                    }
-                    left = true;
-                    if (fill.cuts.length === 0) {
-                        // This stream takes nothing in the fragment: it stays where it is.
-                        pos.push(reopened?.pos[s] ?? { child: items[0].child + base, line: 0 });
-                        return;
-                    }
-                    moved = true;
-                    used = Math.max(used, fill.used);
-                    const b = breaks[fill.cuts[fill.cuts.length - 1]];
-                    const it = items[b.item];
-                    if (b.line === 0) {
-                        pos.push({ child: it.child + base, line: 0 });
-                        return;
-                    }
-                    // The sub-column widths the paragraph's lines are set at.
-                    const before = it.lineBase > 0 ? reopened?.pos[s]?.widths : undefined;
-                    const lastW = before?.[before.length - 1];
-                    const widths = !before || before.length === 0
-                        ? [{ fromLine: 0, width: g.columnWidth }]
-                        : Math.abs(lastW.width - g.columnWidth) <= 0.5 ? before : [...before, { fromLine: it.lineBase, width: g.columnWidth }];
-                    pos.push({ child: it.child + base, line: it.lineBase + b.line, widths });
-                });
-                if (!moved || !left)
-                    continue;
-                candidates.push({
-                    cut: { child: Math.min(...pos.map((p) => p.child)), line: 0, group: { open: g.open + base, pos } },
-                    bottom: g.top + used,
-                });
-            }
-        }
-        const insideGroup = (cut) => !cut.group && L.groups.some(([gs, ge]) => (cut.line === 0 ? gs < cut.child && cut.child <= ge : gs < cut.child && cut.child < ge));
-        const viable = candidates
-            .filter((c) => !insideGroup(c.cut))
-            .sort((a, b) => b.bottom - a.bottom);
-        // A wrapped code line stays with its continuations when a cut
-        // elsewhere fits (#624).
-        viable.sort((a, b) => (a.soft ? 1 : 0) - (b.soft ? 1 : 0));
-        for (const c of viable) {
-            if (c.bottom + tail > roomPx + 0.01)
-                continue;
-            const result = L.layoutRange(from, c.cut, width, frameId, continuation, mirrored);
-            if (result.totalHeight <= roomPx + 0.01)
-                return { to: c.cut, result };
-        }
-        return null;
-    };
-    /** Absolute content indices of the children a fragment from cut `from`
-     *  to cut `to` of `L` touches, for the fragment's source range. */
-    const fragmentRange = (L, from, to) => ({ firstChildIdx: L.childBase + from.child, lastChildIdx: L.childBase + (to.line > 0 ? to.child : to.child - 1) });
-    /** The (rest of the) box is taller than an empty, full-height column —
-     *  a whole page's content area for a page-span box: no column could
-     *  hold it, so even a keep-together box splits (with the rules of a
-     *  `keepTogether: false` one) rather than overflow. */
-    const tallerThanColumn = (result) => result.totalHeight > contentArea.height + 0.01;
+    const splitCalloutFragment = (L, from, width, roomPx, frameId, continuation, minLines, mirrored = false) => splitCalloutFragmentIn(framePass, L, from, width, roomPx, frameId, continuation, minLines, mirrored);
+    const tallerThanColumn = (result) => tallerThanColumnIn(framePass, result);
     const markFragment = (result, part, continued) => {
         if (result.frame.callout) {
             result.frame.callout.part = part;
@@ -5933,6 +5720,174 @@ function placeDocumentPass(content, config, cache, options, hints) {
         inlineGapOwed = pendingSpacing > 0 ? { afterIdx: blockIdx, pending: pendingSpacing, exact: owed } : null;
         return undefined;
     };
+    // --- Blocks of the contents kept together (`toc.groups`, #850) -----------
+    /** The measure context of content block `idx` (a part's, a styled
+     *  section's). */
+    const measureCtxOf = (idx) => (partPlan.byBlock[idx] ? partMeasureCtx : sectionMeasureCtx(sectionPlan.byBlock[idx]));
+    /** The rows of the contents block whose lead row is `idx`, in order (its
+     *  head's repeats aside). */
+    const tocGroupRows = (idx) => {
+        const id = contentBlocks[idx]?.toc?.group?.id;
+        const rows = [];
+        if (id === undefined)
+            return rows;
+        for (let i = idx; i < contentBlocks.length; i++) {
+            const b = contentBlocks[i];
+            if (isMarkerBlock(b))
+                continue;
+            if (b.toc?.group?.id !== id)
+                break;
+            if (b.toc.group.role !== 'continuation')
+                rows.push(i);
+        }
+        return rows;
+    };
+    /**
+     * The room the contents block led by row `idx` takes in a column `width`
+     * wide, from the top of its first row (the space above it aside): `whole`
+     * for every row, `lead` down to the `minEntries`-th entry under its head
+     * (the least a cut block keeps with its head). The rows are spaced as
+     * the layout spaces them, by the larger of the margins that meet.
+     */
+    const tocGroupNeed = (idx, width) => {
+        const rows = tocGroupRows(idx);
+        if (rows.length < 2)
+            return undefined;
+        const min = contentBlocks[idx].toc.group.minEntries;
+        let height = 0;
+        let lead = 0;
+        let prevBottom;
+        let afterHead = -1;
+        for (const i of rows) {
+            const raw = contentBlocks[i];
+            const m = measureContentBlock(raw, i, width, measureCtxOf(i));
+            if (!m)
+                return undefined;
+            const style = m.kind.style;
+            if (prevBottom !== undefined)
+                height += Math.max(prevBottom, style.marginTopPx);
+            height += m.measured.lines.length * style.lineHeightPx;
+            prevBottom = style.marginBottomPx;
+            if (raw.toc.group.role === 'head')
+                afterHead = 0;
+            else if (afterHead >= 0 && raw.toc.kind === 'entry')
+                afterHead++;
+            if (afterHead >= 0 && afterHead <= min)
+                lead = height;
+        }
+        return { whole: height, lead };
+    };
+    /**
+     * Whether the repeat of a contents block's head row at `idx` is set: the
+     * entry after it goes on in a fresh column, which the repeat opens. When
+     * the entry does not fit in the room the cursor's column has left (an
+     * entry is not cut between columns once its block is), the cursor moves
+     * on to the next column first.
+     */
+    const tocContinuationOpens = (idx) => {
+        let next = idx + 1;
+        while (next < contentBlocks.length && isMarkerBlock(contentBlocks[next]))
+            next++;
+        const entry = contentBlocks[next];
+        if (entry?.toc?.group?.id !== contentBlocks[idx].toc.group.id)
+            return false;
+        const col = currentColumn(doc, cursor);
+        if (col.blocks.length === 0)
+            return true;
+        const m = measureContentBlock(entry, next, col.bbox.width, measureCtxOf(next));
+        if (!m)
+            return false;
+        const style = m.kind.style;
+        const need = m.measured.lines.length * style.lineHeightPx + Math.max(pendingSpacing, style.marginTopPx);
+        if (need <= col.availableHeight + FIT_EPS)
+            return false;
+        pendingSpacing = 0;
+        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+        return true;
+    };
+    /** A `tocGroupSplit` warning for each contents block set in more than
+     *  one column, with its head's title and the page it is cut on. */
+    const tocGroupWarnings = () => {
+        const placed = new Map();
+        for (const page of doc.pages) {
+            for (const c of page.columns) {
+                for (const b of c.blocks) {
+                    const raw = b.contentIndex !== undefined ? contentBlocks[b.contentIndex] : undefined;
+                    const group = raw?.toc?.group;
+                    if (!raw || !group || group.role === 'continuation')
+                        continue;
+                    const at = placed.get(group.id) ?? { title: group.title, columns: new Set(), pageIndex: page.index, source: raw };
+                    at.columns.add(`${page.index}:${c.index}`);
+                    placed.set(group.id, at);
+                }
+            }
+        }
+        const out = [];
+        for (const at of placed.values()) {
+            if (at.columns.size < 2)
+                continue;
+            out.push({
+                kind: 'tocGroupSplit',
+                title: at.title,
+                columns: at.columns.size,
+                sourceStart: at.source.sourceStart + bodyOffset,
+                sourceEnd: at.source.sourceEnd + bodyOffset,
+                pageIndex: at.pageIndex,
+            });
+        }
+        return out;
+    };
+    /** Content indices a composed page set in its frames: the main loop
+     *  passes over them. */
+    const composedLaid = new Set();
+    /** The composed pages' layout warnings (`frameOverflow`). */
+    const composedNotes = [];
+    /** Set the composed page `planned` on a fresh page (#855). */
+    const placeComposedPage = (planned, fence) => {
+        pendingSpacing = 0;
+        closeFlowSegment(planned.startIdx);
+        leaveCurrentPage();
+        cursor.columnIndex = 0;
+        const page = doc.pages[cursor.pageIndex];
+        page.columns = [createVDTColumn(0, page.contentArea)];
+        // The physical side: a recto has an odd folio (in either binding).
+        const parity = (page.index + pageIndexOffset) % 2 === 0 ? 'recto' : 'verso';
+        const template = resolvePageTemplate(templateSource, fence.template, { parity });
+        const frameless = calloutStyles.find((st) => st.id === FRAME_STYLE_ID);
+        const frames = designFramesOn(page);
+        const area = template.area === 'trim' ? frames.page : template.area === 'bleed' ? frames.bleed : page.contentArea;
+        const out = layoutComposedPage({
+            pass: framePass,
+            page,
+            template,
+            fence,
+            startIdx: planned.startIdx,
+            endIdx: planned.endIdx,
+            stories: planned.stories,
+            styleOf: (frame) => frameStyleOf((frame.style ? resolved.calloutStyles.find((st) => st.id === frame.style) : undefined) ?? frameless, frame),
+            areas: { area, page: frames.page, bleed: frames.bleed },
+            dpi,
+            emPx: bodyStyle.fontSizePx,
+            bodyOffset,
+            mirrored: mirroredOf(page),
+            pushGapPx: wrapGapPx(resolved.layout.wrap?.gap, dpi, bodyStyle.fontSizePx, floatGapPx),
+        });
+        page.composed = out.composed;
+        const floats = (page.floats ??= []);
+        for (const b of out.blocks) {
+            floats.push(b);
+            doc.blocks.push(b);
+        }
+        composedNotes.push(...out.warnings);
+        for (const [head, story] of planned.stories) {
+            if (!out.laid.has(head))
+                continue;
+            for (let i = story.startIdx; i <= story.plan.endIdx; i++)
+                composedLaid.add(i);
+        }
+        pendingComposedBreak = 'page';
+        flushPendingNumberingAtBoundary();
+    };
     /** The first block of the document that sets something: a heading there
      *  opens the document's first page (`openerPages`, #749). */
     const firstFlowBlockIdx = contentBlocks.findIndex((b) => !isMarkerBlock(b) && b.type !== 'directive');
@@ -5941,11 +5896,18 @@ function placeDocumentPass(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];
+        // Blocks a composed page set in its frames (#855) are done.
+        if (composedLaid.has(blockIdx))
+            continue;
         // 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);
+        // The repeat of a contents block's head row (#850): set where a cut
+        // block goes on in a fresh column, skipped everywhere else.
+        if (rawBlock.toc?.group?.role === 'continuation' && !tocContinuationOpens(blockIdx))
+            continue;
         // 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
@@ -6153,6 +6115,39 @@ function placeDocumentPass(content, config, cache, options, hints) {
             pendingPaperBreak = false;
             breakForPaper(blockIdx);
         }
+        // A composed page (`::::page{template=…}`, #855): it owns a fresh page,
+        // its template's frames filled with its stories (`layoutComposedPage`);
+        // nothing flows on it, and what follows starts on the next page. A
+        // story whose frame this side lacks, and content no frame takes, are
+        // set in the flow there. A page whose template is unknown is set in
+        // the flow on pages of its own (`templateUnknown`).
+        if (rawBlock.type === 'containerStart' && rawBlock.containerName === 'composedPage') {
+            const planned = composedPlans.get(blockIdx);
+            pendingComposedBreak = false;
+            if (planned && rawBlock.composedPage)
+                placeComposedPage(planned, rawBlock.composedPage);
+            else
+                breakForPaper(blockIdx);
+            continue;
+        }
+        if (rawBlock.type === 'containerEnd' && rawBlock.containerName === 'composedPage') {
+            // (Set to `'page'` by `placeComposedPage`, a closure the flow
+            // analysis does not follow.)
+            if (pendingComposedBreak !== 'page')
+                pendingComposedBreak = 'flow';
+            continue;
+        }
+        const composedBreak = pendingComposedBreak;
+        if (composedBreak === 'flow') {
+            pendingComposedBreak = false;
+            breakForPaper(blockIdx);
+        }
+        else if (composedBreak === 'page') {
+            pendingComposedBreak = false;
+            pendingSpacing = 0;
+            leaveCurrentPage();
+            flushPendingNumberingAtBoundary();
+        }
         // `:::page`: a comic page owns a fresh page — its panels, split lines
         // and lettering laid out on the sheet (`layoutComicPage`); nothing
         // flows on it, and what follows starts on the next page.
@@ -7389,6 +7384,35 @@ function placeDocumentPass(content, config, cache, options, hints) {
                     }
                 }
             }
+            // A block of the contents is set whole (`toc.groups.keepTogether`,
+            // `:::toc{keep}`, #850): when its rows do not all fit in the room the
+            // column has left and a full column would hold them, it opens the
+            // next column, with the headings right above it. One taller than a
+            // column is cut, but keeps its head with `minEntriesAfterHead`
+            // entries. Not a block that opens its column, or stands under
+            // nothing but headings: it cannot do better anywhere.
+            if (rawBlock.toc?.group?.lead && partIndex === 0 && curCol.blocks.length > 0) {
+                const headingRun = trailingHeadingRun(curCol);
+                const need = headingRun < curCol.blocks.length ? tocGroupNeed(blockIdx, curCol.bbox.width) : undefined;
+                if (need) {
+                    const room = curCol.availableHeight - spacingBefore;
+                    const asked = need.whole <= contentArea.height + FIT_EPS ? need.whole : need.lead;
+                    if (asked > room + FIT_EPS) {
+                        if (resolved.headings.keepWithNext && headingRun > 0) {
+                            const rolledBack = rollbackHeadings(curCol);
+                            if (rolledBack.length > 0) {
+                                blockIdx = (rolledBack[0].contentIndex ?? blockIdx - rolledBack.length) - 1;
+                                pendingSpacing = 0;
+                                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                                break;
+                            }
+                        }
+                        pendingSpacing = 0;
+                        advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx, onNewPage);
+                        continue;
+                    }
+                }
+            }
             // A short list is set whole (`bodyText.shortListSplit: 'avoid'`,
             // #749): when its items do not all fit under what the column holds
             // and an empty column would hold them, the list opens the next
@@ -8147,8 +8171,11 @@ function placeDocumentPass(content, config, cache, options, hints) {
         floatShrinkWarningsByDoc.set(doc, shrunk);
     if (textWrapNotes.length > 0 || columnsNotes.length > 0)
         textWrapWarningsByDoc.set(doc, [...textWrapNotes, ...columnsNotes]);
+    // Composed pages (#855): frames whose content does not fit.
+    if (composedNotes.length > 0)
+        composedWarningsByDoc.set(doc, composedNotes);
     // The composition rules (#749): short lists cut, floats on opener pages.
-    const ruleNotes = [...shortListWarnings(), ...openerFloatNotes];
+    const ruleNotes = [...shortListWarnings(), ...openerFloatNotes, ...tocGroupWarnings()];
     if (ruleNotes.length > 0)
         compositionWarningsByDoc.set(doc, ruleNotes);
     const { proposals: citingPageProposals, refused: citingPageRefused } = settleCitingPageFloats();
@@ -8221,7 +8248,7 @@ export function* buildDocumentGen(content, config, cache, options) {
     // cap; words of a joining script that run past their line, and styles
     // whose letter-spacing such words do not take.
     // Line numbers set over a float of the side column (#621).
-    const loose = [...cjkLooseLineWarnings(doc), ...raggedLineWarnings(doc), ...wordOverflowWarnings(doc), ...(joiningSpacingWarnings.get(doc) ?? []), ...(dropCapWarningsByDoc.get(doc) ?? []), ...lineNumberWarnings(doc), ...codeOverflowWarnings(doc), ...(floatShrinkWarningsByDoc.get(doc) ?? []), ...(textWrapWarningsByDoc.get(doc) ?? []), ...(compositionWarningsByDoc.get(doc) ?? [])];
+    const loose = [...cjkLooseLineWarnings(doc), ...raggedLineWarnings(doc), ...wordOverflowWarnings(doc), ...(joiningSpacingWarnings.get(doc) ?? []), ...(dropCapWarningsByDoc.get(doc) ?? []), ...lineNumberWarnings(doc), ...codeOverflowWarnings(doc), ...(floatShrinkWarningsByDoc.get(doc) ?? []), ...(textWrapWarningsByDoc.get(doc) ?? []), ...(compositionWarningsByDoc.get(doc) ?? []), ...(composedWarningsByDoc.get(doc) ?? [])];
     // Side boxes and side floats set on pages after the text, and what the
     // layout could place nowhere (#639).
     loose.push(...afterTextWarnings(doc), ...(unplacedByDoc.get(doc) ?? []));
@@ -8252,6 +8279,8 @@ export function* buildDocumentGen(content, config, cache, options) {
     const harakat = annotateArabicMarks(doc);
     // The rules over `*…*` runs under `bodyText.emphasis: 'overline'`.
     overlineEmphasis(doc);
+    // The bands of the highlight marks (`:mark[…]`, #888).
+    highlightDocument(doc);
     // Faces the text was set in that the font set could not give (#629).
     const fallbacks = fontSet && resolveDebugConfig(config?.debug).warnings.missingFont
         ? fontFallbacks(documentFontFaces(doc), fontSet).map((f) => ({ kind: 'fontFallback', family: f.family, weight: f.weight, style: f.style, reason: f.reason }))
@@ -8262,7 +8291,7 @@ export function* buildDocumentGen(content, config, cache, options) {
     // Config values the build replaced (an unknown number format, a font
     // stack, a side column no column width can take): walked once per build,
     // not per pass — they belong to no page.
-    const configWarnings = collectConfigWarnings(config);
+    const configWarnings = collectConfigWarnings(config, { resources: content.resources, metadata: doc.metadata });
     if (configWarnings.length > 0)
         doc.configWarnings = configWarnings;
     return doc;
@@ -8280,6 +8309,8 @@ const floatShrinkWarningsByDoc = new WeakMap();
 /** The `textWrap` warnings of a build (#627) and its `columnsTooNarrow`
  *  ones (#634), found by its last pass. */
 const textWrapWarningsByDoc = new WeakMap();
+/** The composed pages' layout warnings of a pass (`frameOverflow`, #855). */
+const composedWarningsByDoc = new WeakMap();
 /** The `shortListSplit` and `openerFloat` warnings of a build (#749),
  *  found by its last pass. */
 const compositionWarningsByDoc = new WeakMap();