postext 1.34.0 → 1.35.0

package/dist/pipeline/build.js

@@ -2,6 +2,7 @@ import { withBitmapResolutions } from '../bitmapResolution';
 import { plainTitleBreaks } from '../parse/inlineFormatting';
 import { dimensionToPx } from '../units';
 import { createVDTDocument, createVDTBlock, createBoundingBox, createVDTColumn, pageIsMirrored, pageIsVertical, flowRectToPage, } from '../vdt';
+import { figureLabels } from './buildMeasurement';
 import { anchorBox } from '../design/layout';
 import { parseMarkdownMemo, spaceDirectiveLines } from '../parse';
 import { buildPageLabels, computeHeadingNumbering, parseNumberFormat, } from '../numbering';
@@ -34,6 +35,10 @@ 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 { layoutComposedSpread } from '../composed/spread';
+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 +54,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 +82,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 +485,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.
@@ -516,6 +528,14 @@ function placeDocumentPass(content, config, cache, options, hints) {
     for (const [id, entry] of Object.entries(resourceNumbering)) {
         resourceNumberById.set(id, entry.number);
     }
+    // The labels of each `:::figure` (#862), by resource: a figure that
+    // floats is laid out by its id alone.
+    const figureLabelsById = new Map();
+    for (const b of contentBlocks) {
+        const labels = b.resourceId !== undefined && !figureLabelsById.has(b.resourceId) ? figureLabels(b) : undefined;
+        if (labels)
+            figureLabelsById.set(b.resourceId, labels);
+    }
     // Resolve styles
     const bodyStyle = resolveBodyStyle(resolved);
     // The callout styles, with the frameless box of the page-span embeds
@@ -525,6 +545,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 +558,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 +590,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) {
@@ -1216,7 +1255,8 @@ function placeDocumentPass(content, config, cache, options, hints) {
         const { block: rb, totalHeight } = laid;
         const id = slice && slice.startRow > 0 ? `float-${resourceId}-cont-${slice.startRow}` : `float-${resourceId}`;
         const blk = createVDTBlock(id, 'resource', bodyStyle.fontString, bodyStyle.color, bodyStyle.textAlign);
-        blk.resourceBlock = rb;
+        const labels = figureLabelsById.get(resourceId);
+        blk.resourceBlock = labels ? { ...rb, labels } : rb;
         blk.dirty = false;
         blk.snappedToGrid = false;
         blk.bbox = createBoundingBox(x, 0, width, totalHeight);
@@ -2986,7 +3026,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)
@@ -3368,7 +3408,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);
@@ -3502,7 +3542,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);
@@ -3708,8 +3748,11 @@ 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) ended: the next placed block opens
-     *  a new page. */
+    /** 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
@@ -3740,7 +3783,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
@@ -3905,16 +3948,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. */
@@ -3925,85 +3966,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
@@ -4029,192 +4006,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;
@@ -6055,6 +5848,102 @@ function placeDocumentPass(content, config, cache, options, hints) {
         }
         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), or a spread
+     *  template on the two facing pages from the next verso (#861). */
+    const placeComposedPage = (planned, fence) => {
+        pendingSpacing = 0;
+        closeFlowSegment(planned.startIdx);
+        leaveCurrentPage();
+        cursor.columnIndex = 0;
+        const frameless = calloutStyles.find((st) => st.id === FRAME_STYLE_ID);
+        const common = (page) => ({
+            pass: framePass,
+            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),
+            dpi,
+            emPx: bodyStyle.fontSizePx,
+            bodyOffset,
+            mirrored: mirroredOf(page),
+            pushGapPx: wrapGapPx(resolved.layout.wrap?.gap, dpi, bodyStyle.fontSizePx, floatGapPx),
+        });
+        const placed = [];
+        let laid;
+        const sheet = resolvePageTemplate(templateSource, fence.template, { spread: true });
+        if (sheet?.spread) {
+            // A spread opens on a verso, a parity blank before it when needed,
+            // as a comic spread does; the recto after it takes the other half.
+            breakToEvenPage();
+            const verso = doc.pages[cursor.pageIndex];
+            verso.columns = [createVDTColumn(0, verso.contentArea)];
+            const start = cursor.pageIndex;
+            do {
+                advanceToNextColumn(doc, cursor, geomResolved, contentArea, pageWidthPx, pageHeightPx);
+            } while (cursor.pageIndex === start);
+            const recto = doc.pages[cursor.pageIndex];
+            recto.columns = [createVDTColumn(0, recto.contentArea)];
+            cursor.columnIndex = 0;
+            // The sheet is laid in the pages' flow: the left page first, or the
+            // right one where the flow is mirrored (right to left).
+            const versoIsLeft = resolved.page.binding !== 'right';
+            const flowMirrored = pageIsMirrored(verso);
+            const left = versoIsLeft ? verso : recto;
+            const right = versoIsLeft ? recto : verso;
+            const out = layoutComposedSpread({
+                ...common(flowMirrored ? right : left),
+                template: sheet,
+                first: flowMirrored ? right : left,
+                second: flowMirrored ? left : right,
+                firstSide: flowMirrored ? 'right' : 'left',
+                trim: pageMetrics.physical.trimBox,
+                bleed: pageMetrics.physical.bleedBox,
+            });
+            placed.push(...out.sides);
+            composedNotes.push(...out.warnings);
+            laid = out.laid;
+        }
+        else {
+            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 frames = designFramesOn(page);
+            const area = template.area === 'trim' ? frames.page : template.area === 'bleed' ? frames.bleed : page.contentArea;
+            const out = layoutComposedPage({
+                ...common(page),
+                page,
+                template,
+                areas: { area, page: frames.page, bleed: frames.bleed },
+            });
+            placed.push({ page, composed: out.composed, blocks: out.blocks });
+            composedNotes.push(...out.warnings);
+            laid = out.laid;
+        }
+        for (const { page, composed, blocks } of placed) {
+            page.composed = composed;
+            const floats = (page.floats ??= []);
+            for (const b of blocks) {
+                floats.push(b);
+                doc.blocks.push(b);
+            }
+        }
+        for (const [head, story] of planned.stories) {
+            if (!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');
@@ -6063,6 +5952,9 @@ 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];
@@ -6279,26 +6171,39 @@ function placeDocumentPass(content, config, cache, options, hints) {
             pendingPaperBreak = false;
             breakForPaper(blockIdx);
         }
-        // A composed page (`::::page{template=…}`, #854). Until templates are
-        // laid out (P4, #855) its content is set in the flow, in Markdown order
-        // and on pages of its own: the page fence breaks the page as `:::paper`
-        // does, its frames are transparent containers (the generic marker branch
-        // below), and the block after the closing fence opens a new page. P4
-        // replaces this branch with the template layout (DESIGN §5.1).
-        if ((rawBlock.type === 'containerStart' || rawBlock.type === 'containerEnd') && rawBlock.containerName === 'composedPage') {
-            if (rawBlock.type === 'containerStart') {
-                pendingComposedBreak = false;
+        // 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);
-            }
-            else {
-                pendingComposedBreak = true;
-            }
             continue;
         }
-        if (pendingComposedBreak) {
+        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.
@@ -8322,6 +8227,9 @@ 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, ...tocGroupWarnings()];
     if (ruleNotes.length > 0)
@@ -8396,7 +8304,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) ?? []));
@@ -8427,6 +8335,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 }))
@@ -8455,6 +8365,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();