postext 1.35.1 → 1.37.0

package/dist/pipeline/composedLayout.js

@@ -1,3 +1,6 @@
+import { pageIsMirrored } from '../vdt';
+import { contourBounds, scaleContourAbout, shiftContour } from '../contour';
+import { frameContour } from '../composed/contour';
 import { dimensionToPx } from '../units';
 import { frameBounds } from '../composed/paint';
 import { FRAME_ATTR } from '../composed/wrap';
@@ -5,21 +8,455 @@ import { framePlaceable, nextFrameOf, groupPlaceable, placeBox, unionRect } from
 import { composedOrder, groupOfFrames, layoutGroup } from '../composed/groups';
 import { reflowEvents } from '../composed/reflowLog';
 import { anchorTarget } from '../composed/templates';
+import { continuationTemplate, continuesOffPage } from '../composed/continuation';
 import { resolvePageTemplate } from '../composed/templates';
+import { frameElementId } from '../composed/ids';
 import { offsetCalloutToAbsolute } from './calloutLayout';
+import { isMarkerBlock } from './buildHelpers';
 import { CUT_START, fragmentRange, makeCalloutLayouter, splitCalloutFragment } from './frameLayout';
 const MM_PER_IN = 25.4;
-export function layoutComposedPage(input) {
-    const { pass, page, template, fence, dpi } = input;
-    const fi = fence.fenceIndex;
-    const frameIdOf = (name) => `cp${fi}:${name}`;
-    const byName = new Map(template.frames.map((f) => [f.name, f]));
+const NO_FIT = { patches: new Map(), text: new Map(), pictures: new Map(), yieldAll: new Set(), goOn: new Set() };
+/** Step of the text and picture scales the ladder tries (DESIGN §5.4). */
+const FIT_STEP = 0.025;
+/** Lowest text scale an `allowShrink` proposal goes to. */
+const PROPOSAL_MIN_SCALE = 0.5;
+/** Most compositions of one page the ladder and its proposals may run. */
+const COMPOSE_BUDGET = 96;
+/** The scales from just under 1 (or under `from`) down to `min`, in
+ *  {@link FIT_STEP} steps, `min` last. */
+function scaleSteps(min, from = 1) {
+    const out = [];
+    for (let k = 1;; k++) {
+        const s = Math.round((from - k * FIT_STEP) * 1e4) / 1e4;
+        if (s <= min + 1e-6)
+            break;
+        out.push(s);
+    }
+    if (min < from - 1e-6)
+        out.push(Math.round(min * 1e4) / 1e4);
+    return out;
+}
+/** The template with the ladder's patches on its frames. */
+function patchTemplate(template, patches) {
+    if (patches.size === 0)
+        return template;
+    return { ...template, frames: template.frames.map((f) => (patches.has(f.name) ? { ...f, ...patches.get(f.name) } : f)) };
+}
+/** A fixed height (a length, not a percentage). */
+const fixedHeight = (f) => {
+    const h = f.height;
+    return h !== null && typeof h === 'object' && 'value' in h && 'unit' in h ? f.height : undefined;
+};
+/** The frame before each frame of a chain on the page. On a page added by
+ *  continuation (#859) a frame that receives content starts its chain. */
+function chainPrev(template, receivers) {
+    const names = new Set(template.frames.map((f) => f.name));
     const prev = new Map();
     for (const f of template.frames) {
         const n = nextFrameOf(f);
-        if (n && byName.has(n) && !prev.has(n))
+        if (n && names.has(n) && !prev.has(n) && !receivers?.has(n))
             prev.set(n, f.name);
     }
+    return prev;
+}
+const sameCut = (a, b) => a.child === b.child && a.line === b.line && JSON.stringify(a.group ?? null) === JSON.stringify(b.group ?? null);
+export function layoutComposedPage(given) {
+    // A page added by continuation (#859) lays its template with the
+    // continuation's rules (and, for the template laid again, its other
+    // frames collapsed).
+    const input = given.continuing ? { ...given, template: continuationTemplate(given.template, given.continuing) } : given;
+    const { template, fence, dpi } = input;
+    const fi = fence.fenceIndex;
+    const mmPx = dpi / MM_PER_IN;
+    const byName = new Map(template.frames.map((f) => [f.name, f]));
+    const groupOf = groupOfFrames(template);
+    const prev = chainPrev(template, input.continuing?.receivers);
+    const headOf = (name) => {
+        let at = name;
+        const seen = new Set([at]);
+        for (let p = prev.get(at); p !== undefined && !seen.has(p); p = prev.get(at)) {
+            seen.add(p);
+            at = p;
+        }
+        return at;
+    };
+    // Compositions by fit state: the ladder and its proposals ask for some
+    // twice.
+    const memo = new Map();
+    let runs = 0;
+    const keyOf = (tpl, fit) => JSON.stringify([tpl.id, [...fit.patches], [...fit.text], [...fit.pictures], [...fit.yieldAll], [...fit.goOn]]);
+    const compose = (fit, tpl = template) => {
+        const key = keyOf(tpl, fit);
+        const known = memo.get(key);
+        if (known)
+            return known;
+        runs++;
+        const c = composePage(input, patchTemplate(tpl, fit.patches), fit);
+        memo.set(key, c);
+        return c;
+    };
+    const frameIn = (c, name) => c.frames.find((f) => f.name === name);
+    const overflows = (c, name) => (frameIn(c, name)?.overflowPx ?? 0) > 0.5;
+    /** The ladder's last step (#859): the frame is cut at its foot and the
+     *  rest goes on on another page, its text and pictures back at full
+     *  size (they go on anyway). */
+    const goingOn = (f, frame) => {
+        const text = new Map(f.text);
+        text.delete(headOf(frame.name));
+        const pictures = new Map([...f.pictures].filter(([, p]) => p.by !== frame.name));
+        return { ...f, text, pictures, goOn: new Set([...f.goOn, frame.name]) };
+    };
+    // The ladder, frame by frame in template order (ties break there).
+    let fit = NO_FIT;
+    let cur = compose(fit);
+    const tried = new Map();
+    const patched = (f, name, patch) => ({ ...f, patches: new Map([...f.patches, [name, { ...f.patches.get(name), ...patch }]]) });
+    const withText = (f, head, s) => ({ ...f, text: new Map([...f.text, [head, s]]) });
+    const withPictures = (f, heads, s, by) => {
+        const pictures = new Map(f.pictures);
+        for (const h of heads)
+            pictures.set(h, { scale: s, by });
+        return { ...f, pictures };
+    };
+    /** Take `next` when it makes `name` fit; else keep it anyway (each step
+     *  builds on the ones before it at their limit) and say so. */
+    const attempt = (next, name) => {
+        fit = next;
+        cur = compose(fit);
+        return !overflows(cur, name);
+    };
+    /** The largest scale among `steps` (descending) at which `name` fits,
+     *  checked at the lowest first, then by bisection; adopted. */
+    const searchScale = (steps, make, name) => {
+        if (steps.length === 0)
+            return false;
+        if (!attempt(make(steps[steps.length - 1]), name))
+            return false;
+        let lo = 0;
+        let hi = steps.length - 1; // fits at hi
+        while (lo < hi && runs < COMPOSE_BUDGET) {
+            const mid = Math.floor((lo + hi) / 2);
+            if (!overflows(compose(make(steps[mid])), name))
+                hi = mid;
+            else
+                lo = mid + 1;
+        }
+        fit = make(steps[hi]);
+        cur = compose(fit);
+        return true;
+    };
+    /** Story heads of the frame and of its group's frames whose content holds
+     *  a picture. */
+    const pictureHeads = (frame) => {
+        const g = groupOf.get(frame.name);
+        const names = g ? [frame.name, ...g.frames.filter((m) => m !== frame.name)] : [frame.name];
+        const heads = [];
+        for (const n of names) {
+            const head = headOf(n);
+            const story = input.stories.get(head);
+            if (!story || heads.includes(head))
+                continue;
+            for (let i = story.startIdx + 1; i < story.plan.endIdx; i++) {
+                if (input.pass.contentBlocks[i]?.type === 'resourceBlock') {
+                    heads.push(head);
+                    break;
+                }
+            }
+        }
+        return heads;
+    };
+    /** The frame's story sets text (not only pictures): its text can
+     *  shrink. */
+    const holdsText = (frame) => {
+        const story = input.stories.get(headOf(frame.name));
+        if (!story)
+            return false;
+        for (let i = story.startIdx + 1; i < story.plan.endIdx; i++) {
+            const b = input.pass.contentBlocks[i];
+            if (b && b.type !== 'resourceBlock' && b.type !== 'directive' && !isMarkerBlock(b))
+                return true;
+        }
+        return false;
+    };
+    const movesOthers = (frame) => {
+        const g = groupOf.get(frame.name);
+        if (g && g.frames.filter((m) => byName.has(m)).length > 1)
+            return true;
+        return template.frames.some((f) => f.name !== frame.name && !f.grid && anchorTarget(f.placement) === frame.name);
+    };
+    /** `free` applies: a fixed height with room up to a higher `maxHeight`. */
+    const growPatch = (frame) => {
+        const h = fixedHeight(frame);
+        if (!h || !frame.maxHeight)
+            return undefined;
+        if (dimensionToPx(frame.maxHeight, dpi, input.emPx) <= dimensionToPx(h, dpi, input.emPx) + 0.5)
+            return undefined;
+        const min = frame.minHeight && dimensionToPx(frame.minHeight, dpi, input.emPx) > dimensionToPx(h, dpi, input.emPx) ? frame.minHeight : h;
+        return { height: 'auto', minHeight: min };
+    };
+    for (const frame of template.frames) {
+        const name = frame.name;
+        if (!overflows(cur, name) || runs >= COMPOSE_BUDGET)
+            continue;
+        const steps = [];
+        tried.set(name, steps);
+        // 1. Free space: a fixed height grows to its maximum ('auto' heights
+        //    already take the room their area and group leave).
+        steps.push('free');
+        const grow = growPatch(frame);
+        if (grow && attempt(patched(fit, name, grow), name))
+            continue;
+        // 2. Push siblings: the group moved the frames after it and the frames
+        //    that shrink gave space back when it was laid.
+        if (movesOthers(frame))
+            steps.push('push');
+        // 3. Pictures of the frame and its group, down to imageMinScale.
+        const heads = frame.fit.scaleImages ? pictureHeads(frame) : [];
+        if (heads.length > 0 && frame.fit.imageMinScale < 1) {
+            steps.push('scaleImages');
+            if (searchScale(scaleSteps(frame.fit.imageMinScale), (s) => withPictures(fit, heads, s, name), name))
+                continue;
+        }
+        // 4. Redistribute: every other frame of the group gives space (or
+        //    width) back, down to its minimum or its content.
+        const g = groupOf.get(name);
+        if (g && g.frames.filter((m) => byName.has(m)).length > 1) {
+            steps.push('redistribute');
+            if (attempt({ ...fit, yieldAll: new Set([...fit.yieldAll, g.name]) }, name))
+                continue;
+        }
+        // 5. The frame's text (its whole story), down to fit.minScale.
+        if (frame.fit.shrinkText && frame.fit.minScale < 1 && holdsText(frame)) {
+            steps.push('shrinkText');
+            const head = headOf(name);
+            if (searchScale(scaleSteps(frame.fit.minScale), (s) => withText(fit, head, s), name))
+                continue;
+        }
+        // 6. Continuation on another page (`overflow.continueIn: 'next-page'`
+        //    or `'template:<id>'`, #859). On a page added by continuation, a
+        //    frame that would take none of what it receives sends nothing on
+        //    (it would go on for ever): it warns.
+        if (continuesOffPage(frame.overflow.continueIn)) {
+            steps.push('continue');
+            const before = { fit, cur };
+            if (attempt(goingOn(fit, frame), name) && (!input.continuing || cur.spills.get(name)?.advanced !== false))
+                continue;
+            ({ fit, cur } = before);
+        }
+    }
+    // 7. Warn, with what would make each frame that still overflows fit.
+    const warnings = [...(cur.notes ?? [])];
+    const templateAttr = fence.attrSources.template;
+    for (const frame of template.frames) {
+        const vdt = frameIn(cur, frame.name);
+        if (!vdt || vdt.overflowPx <= 0.5)
+            continue;
+        const overflowMm = Math.round((vdt.overflowPx / mmPx) * 10) / 10;
+        const proposals = overflowProposals({
+            frame,
+            vdt,
+            cur,
+            fit,
+            compose,
+            overflows,
+            headOf,
+            withText,
+            patched,
+            groupOf,
+            byName,
+            mmPx,
+            dpi,
+            emPx: input.emPx,
+            alternatives: input.alternatives,
+            templateSource: templateAttr ? { sourceStart: templateAttr.sourceStart + input.bodyOffset, sourceEnd: templateAttr.sourceEnd + input.bodyOffset } : undefined,
+            budgetLeft: () => runs < COMPOSE_BUDGET,
+            holdsText: holdsText(frame),
+        });
+        warnings.push({
+            kind: 'frameOverflow',
+            template: template.id,
+            frame: frame.name,
+            fenceIndex: fi,
+            overflowMm,
+            configPath: frame.configPath,
+            ...(input.locale ? { locale: input.locale } : {}),
+            stepsTried: tried.get(frame.name) ?? ['free'],
+            scale: vdt.scale,
+            ...(vdt.imageScale !== undefined ? { imageScale: vdt.imageScale } : {}),
+            proposals,
+            ...(vdt.sourceStart !== undefined ? { sourceStart: vdt.sourceStart, sourceEnd: vdt.sourceEnd } : {}),
+            pageIndex: input.page.index,
+        });
+    }
+    const { frames, blocks, log, laid, fitted } = cur;
+    // Template order on the page record.
+    const order = new Map(template.frames.map((f, i) => [f.name, i]));
+    frames.sort((a, b) => order.get(a.name) - order.get(b.name));
+    const contentBlocks = input.pass.contentBlocks;
+    const composed = {
+        template: template.id,
+        ...(template.variant ? { variant: template.variant } : {}),
+        fenceIndex: fi,
+        role: template.role,
+        attrs: { ...fence.attrs },
+        attrSources: Object.fromEntries(Object.entries(fence.attrSources).map(([k, v]) => [k, { sourceStart: v.sourceStart + input.bodyOffset, sourceEnd: v.sourceEnd + input.bodyOffset }])),
+        frames,
+        log,
+        configPath: template.configPath,
+        sourceStart: contentBlocks[input.startIdx].sourceStart + input.bodyOffset,
+        sourceEnd: contentBlocks[input.endIdx].sourceEnd + input.bodyOffset,
+    };
+    // What goes on on other pages (#859), in template order.
+    const continuations = [];
+    for (const frame of template.frames) {
+        const spill = cur.spills.get(frame.name);
+        const story = spill ? input.stories.get(spill.head) : undefined;
+        if (!spill || !story)
+            continue;
+        const came = input.continuing?.receivers.get(spill.head);
+        continuations.push({
+            frame: frame.name,
+            fromFrameId: spill.frameId,
+            rule: frame.overflow.continueIn,
+            template: template.id,
+            collapsed: input.continuing?.collapse ?? false,
+            story,
+            cut: spill.cut,
+            pieces: spill.pieces,
+            headBlockId: spill.headBlockId,
+            slot: came?.slot ?? frame.name,
+        });
+    }
+    return { composed, blocks, warnings, laid, ...(fitted.size > 0 ? { fitted } : {}), ...(continuations.length > 0 ? { continuations } : {}) };
+}
+const mmDim = (value) => ({ value, unit: 'mm' });
+/** What would make `frame`'s content fit, each value worked out from the
+ *  shortfall and, where the page can tell, tried on it (DESIGN §5.7). */
+function overflowProposals(c) {
+    const { frame, vdt, cur, fit, mmPx } = c;
+    const name = frame.name;
+    const out = [];
+    const path = (key) => frame.fieldPaths[key] ?? `${frame.configPath}/${key}`;
+    const fits = (next, tpl) => c.budgetLeft() && !c.overflows(c.compose(next, tpl), name);
+    // More shrink: the largest text scale, in 2.5 % steps, at which it fits.
+    const head = c.headOf(name);
+    const from = frame.fit.shrinkText ? Math.min(frame.fit.minScale, vdt.scale) : 1;
+    const steps = scaleSteps(PROPOSAL_MIN_SCALE, from);
+    if (c.holdsText && steps.length > 0 && fits(c.withText(fit, head, steps[steps.length - 1]))) {
+        let lo = 0;
+        let hi = steps.length - 1;
+        while (lo < hi && c.budgetLeft()) {
+            const mid = Math.floor((lo + hi) / 2);
+            if (fits(c.withText(fit, head, steps[mid])))
+                hi = mid;
+            else
+                lo = mid + 1;
+        }
+        out.push({
+            kind: 'allowShrink',
+            path: path('fit/minScale'),
+            value: steps[hi],
+            ...(frame.fit.shrinkText ? {} : { also: [{ path: path('fit/shrinkText'), value: true }] }),
+        });
+    }
+    // A higher maximum: the frame's height plus the shortfall, in whole mm.
+    const fixed = fixedHeight(frame);
+    if (frame.maxHeight || fixed) {
+        const want = Math.ceil((vdt.rect.height + vdt.overflowPx) / mmPx - 1e-6);
+        const patch = { maxHeight: mmDim(want), ...(fixed ? { height: 'auto', minHeight: fixed } : {}) };
+        if (fits(c.patched(fit, name, patch)))
+            out.push({ kind: 'raiseMax', path: path('maxHeight'), value: mmDim(want) });
+    }
+    // A lower minimum on a frame of its group that stands at its minimum
+    // with less content than that: lowered by the shortfall, not below its
+    // content.
+    const g = c.groupOf.get(name);
+    if (g) {
+        for (const other of g.frames) {
+            const f = c.byName.get(other);
+            if (!f || other === name || f.pin || !f.minHeight)
+                continue;
+            const box = cur.frames.find((x) => x.name === other);
+            if (!box)
+                continue;
+            const minPx = dimensionToPx(f.minHeight, c.dpi, c.emPx);
+            const need = cur.needs.get(other)?.() ?? 0;
+            if (Math.abs(box.rect.height - minPx) > 0.5 || need >= minPx - mmPx)
+                continue;
+            const lowered = Math.max(Math.ceil(need / mmPx - 1e-6), Math.floor((minPx - vdt.overflowPx) / mmPx + 1e-6));
+            if (lowered * mmPx >= minPx - 0.5)
+                continue;
+            if (fits(c.patched(fit, other, { minHeight: mmDim(lowered) }))) {
+                out.push({ kind: 'lowerMin', path: f.fieldPaths.minHeight ?? `${f.configPath}/minHeight`, value: mmDim(lowered), frame: other });
+            }
+        }
+    }
+    // Continue on the next page (#859 lays it out).
+    if (!frame.overflow.continueIn)
+        out.push({ kind: 'continueNextPage', path: path('overflow/continueIn'), value: 'next-page' });
+    // Another template of the book with a frame of this name, where the
+    // content fits as it is.
+    for (const alt of c.alternatives?.() ?? []) {
+        if (!c.budgetLeft())
+            break;
+        if (!alt.frames.some((f) => f.name === name))
+            continue;
+        const trial = c.compose(NO_FIT, alt);
+        const laidThere = trial.frames.find((f) => f.name === name);
+        if (laidThere && laidThere.blockIds.length > 0 && laidThere.overflowPx <= 0.5) {
+            out.push({ kind: 'useTemplate', value: alt.id, ...(c.templateSource ?? {}) });
+            break;
+        }
+    }
+    // Shorter text: the lines that do not fit, at the frame's characters a
+    // line.
+    const lines = cur.blocks.filter((b) => vdt.blockIds.includes(b.id) && b.type !== 'resource').flatMap((b) => b.lines.filter((l) => l.text.length > 0));
+    if (lines.length > 0) {
+        // Characters of a full line: the lines that do not end their paragraph.
+        const full = lines.filter((l) => !l.isLastLine);
+        const sample = full.length > 0 ? full : lines;
+        const perLine = sample.reduce((n, l) => n + l.text.length, 0) / sample.length;
+        const lineH = (lines.reduce((h, l) => h + l.bbox.height, 0) / lines.length) * vdt.scale;
+        if (lineH > 0) {
+            const over = Math.ceil(vdt.overflowPx / lineH - 1e-6);
+            out.push({ kind: 'shortenText', value: Math.ceil(over * perLine), ...(vdt.sourceStart !== undefined ? { sourceStart: vdt.sourceStart, sourceEnd: vdt.sourceEnd } : {}) });
+        }
+    }
+    return out;
+}
+/** A frame style whose box keeps its drawn size when the frame's text is
+ *  set at `scale` (#858): the frame is laid out `1 / scale` as large and
+ *  painted at `scale`, so its padding, border, corner radius, stripe and
+ *  tab are laid out `1 / scale` as large to come out as drawn. Only the
+ *  text and what it holds shrink: padding that keeps room for the photos
+ *  set over a box stays that room. */
+export function keepChromeAt(style, scale) {
+    if (scale === 1)
+        return style;
+    const d = (v) => ({ ...v, value: v.value / scale });
+    const p = style.padding;
+    return {
+        ...style,
+        padding: { top: d(p.top), right: d(p.right), bottom: d(p.bottom), left: d(p.left) },
+        border: { ...style.border, width: d(style.border.width) },
+        borderRadius: d(style.borderRadius),
+        stripe: { ...style.stripe, width: d(style.stripe.width) },
+        ...(style.label
+            ? { label: { ...style.label, height: d(style.label.height), paddingX: d(style.label.paddingX), offset: d(style.label.offset), inset: d(style.label.inset), rule: { ...style.label.rule, width: d(style.label.rule.width) } } }
+            : {}),
+    };
+}
+/** Lay out every frame of the page once, with the reflow ladder's `fit`. */
+function composePage(input, template, fit) {
+    const { pass, fence, dpi } = input;
+    const fi = fence.fenceIndex;
+    const cont = input.continuing;
+    /** A frame's id: `cp<fence>:<name>`; on a page added by continuation
+     *  (#859) `~<k>`, a frame that receives content named by the frame of
+     *  the fence's page that first sent it on. */
+    const frameIdOf = (name) => (cont ? frameElementId(fi, cont.receivers.get(name)?.slot ?? name, cont.generation) : frameElementId(fi, name));
+    const byName = new Map(template.frames.map((f) => [f.name, f]));
+    const prev = chainPrev(template, cont?.receivers);
     /** The head of the chain a frame belongs to. */
     const headOf = (name) => {
         let at = name;
@@ -30,11 +467,34 @@ export function layoutComposedPage(input) {
         }
         return at;
     };
+    /** The text scale of a frame's story (#858). */
+    const textScale = (frame) => fit.text.get(headOf(frame.name)) ?? 1;
+    /** The style a frame is laid out in: its box as drawn at any text scale. */
+    const styleOf = (frame) => {
+        const style = keepChromeAt(input.styleOf(frame), textScale(frame));
+        if (!fit.goOn.has(frame.name))
+            return style;
+        // A frame cut for another page (#859) ends with its mark: its own
+        // words, none (`false`), or its style's localized ones.
+        const mark = frame.overflow.mark;
+        return { ...style, continuesMarkerEnabled: mark !== false, continuesMarker: typeof mark === 'string' ? mark : style.continuesMarker };
+    };
+    /** The scale of a frame's pictures (#858), below 1, or undefined. */
+    const pictureScale = (frame) => fit.pictures.get(headOf(frame.name))?.scale;
+    /** Rectangles in a frame's box coordinates, in its laid-out (scaled)
+     *  coordinates. */
+    const unscale = (rs, s) => rs && s !== 1
+        ? rs.map((r) => ({ x: r.x / s, y: r.y / s, width: r.width / s, height: r.height / s, ...(r.contour ? { contour: scaleContourAbout(r.contour, 0, 0, 1 / s) } : {}) }))
+        : rs;
     /** Place and fill every frame. `seed`: the boxes of the frames that push
      *  text, from a first run, so a frame placed before one that pushes it
      *  (the photo anchored to its box) still runs round it. */
-    const run = (seed) => {
+    const run = (seed, seedShapes) => {
         const pushRects = new Map();
+        /** The shapes of the frames that push with their pictures' contour (#883). */
+        const pushShapes = new Map();
+        /** Pictures of a contour push whose shape is not known (#883). */
+        const notes = [];
         const states = new Map();
         const stateOf = (frame) => {
             const head = headOf(frame.name);
@@ -45,13 +505,16 @@ export function layoutComposedPage(input) {
             const headFrame = byName.get(head);
             if (!story || !headFrame)
                 return undefined;
+            // Content from the page before (#859) goes on where it was cut, its
+            // blocks numbered on from its pieces there.
+            const came = cont?.receivers.get(head);
             const st = {
                 story,
-                L: makeCalloutLayouter(pass, story.startIdx, story.plan, input.styleOf(frame)),
-                cut: CUT_START,
-                pieces: 0,
-                headBlockId: frameIdOf(head),
-                headFrameId: frameIdOf(head),
+                L: makeCalloutLayouter(pass, story.startIdx, story.plan, styleOf(frame)),
+                cut: came?.cut ?? CUT_START,
+                pieces: came?.pieces ?? 0,
+                headBlockId: came?.headBlockId ?? frameIdOf(head),
+                headFrameId: came?.fromFrameId ?? frameIdOf(head),
             };
             states.set(head, st);
             return st;
@@ -82,10 +545,16 @@ export function layoutComposedPage(input) {
         const frames = [];
         const vdtByName = new Map();
         const blocks = [];
-        const warnings = [];
         const overflowLog = [];
+        const fitLog = [];
+        const needs = new Map();
+        /** What `fitBox` did to each frame (#861), last placement wins. */
+        const fitted = new Map();
         const laid = new Set();
-        const pushed = seed ? [...seed].map(([name, box]) => ({ name, box })) : [];
+        const spills = new Map();
+        const pushed = seed
+            ? [...seed].map(([name, box]) => ({ name, box, ...(seedShapes?.get(name) ? { contour: seedShapes.get(name) } : {}) }))
+            : [];
         /** The rectangles of the pushing frames placed so far that `rect`
          *  meets, in the frame block's coordinates. */
         const exclusionsFor = (frame, rect, open) => {
@@ -94,11 +563,17 @@ export function layoutComposedPage(input) {
             for (const p of pushed) {
                 if (p.name === frame.name)
                     continue;
-                const b = p.box;
+                // A contour (#883) pushes with its shape, its margin round it.
+                const cb = p.contour ? contourBounds(p.contour) : undefined;
+                const b = cb ?? p.box;
+                const e = cb ? 0 : g;
                 const below = open ? true : b.y < rect.y + rect.height;
-                if (b.x - g >= rect.x + rect.width || b.x + b.width + g <= rect.x || !below || b.y + b.height + g <= rect.y)
+                if (b.x - e >= rect.x + rect.width || b.x + b.width + e <= rect.x || !below || b.y + b.height + e <= rect.y)
                     continue;
-                out.push({ x: b.x - g - rect.x, y: b.y - g - rect.y, width: b.width + 2 * g, height: b.height + 2 * g });
+                out.push({
+                    x: b.x - e - rect.x, y: b.y - e - rect.y, width: b.width + 2 * e, height: b.height + 2 * e,
+                    ...(cb && p.contour ? { contour: shiftContour(p.contour, -rect.x, -rect.y) } : {}),
+                });
             }
             return out.length > 0 ? out : undefined;
         };
@@ -107,7 +582,7 @@ export function layoutComposedPage(input) {
             // Each frame of a chain sets the story in its own style: the cuts are
             // positions in the story's blocks, the same in any.
             if (st)
-                st.L = makeCalloutLayouter(pass, st.story.startIdx, st.story.plan, input.styleOf(frame));
+                st.L = makeCalloutLayouter(pass, st.story.startIdx, st.story.plan, styleOf(frame));
             // A frame continues its story only once the frame before it in the
             // chain was filled (a frame placed before it, through an anchor, starts
             // empty).
@@ -119,9 +594,13 @@ export function layoutComposedPage(input) {
             return { frame, st, before, holds, continuation, blockId };
         };
         /** The content's height at `width`, running round the pushing frames
-         *  below the top of `at` (the frame's box as first placed). */
+         *  below the top of `at` (the frame's box as first placed). A frame
+         *  whose text the ladder scales (#858) is laid out `1 / scale` as
+         *  wide and is `scale` as tall as that. */
         const naturalOf = (p, at) => {
             const memo = new Map();
+            const s = textScale(p.frame);
+            const pic = pictureScale(p.frame);
             return (width) => {
                 if (!p.holds)
                     return 0;
@@ -129,10 +608,12 @@ export function layoutComposedPage(input) {
                 const known = memo.get(key);
                 if (known !== undefined)
                     return known;
-                const exclusions = at ? exclusionsFor(p.frame, { ...at, width }, true) : undefined;
-                const r = p.st.L.layoutRange(p.st.cut, p.st.L.end, width, p.blockId, p.continuation, input.mirrored, exclusions ? { exclusions } : undefined);
-                memo.set(key, r.totalHeight);
-                return r.totalHeight;
+                const exclusions = at ? unscale(exclusionsFor(p.frame, { ...at, width }, true), s) : undefined;
+                const opts = { ...(exclusions ? { exclusions } : {}), ...(pic !== undefined ? { pictureScale: pic } : {}) };
+                const r = p.st.L.layoutRange(p.st.cut, p.st.L.end, width / s, p.blockId, p.continuation, input.mirrored, opts.exclusions || opts.pictureScale !== undefined ? opts : undefined);
+                const h = r.totalHeight * s;
+                memo.set(key, h);
+                return h;
             };
         };
         /** `placeBox`, then the box the page lets the frame take (`fitBox`:
@@ -143,10 +624,18 @@ export function layoutComposedPage(input) {
             const r = placeBox(placeable, template, ctx, refs, nat);
             if (!input.fitBox)
                 return r;
-            const fitted = input.fitBox(frame, r);
-            if (Math.abs(fitted.width - r.width) < 0.01)
-                return fitted;
-            return input.fitBox(frame, placeBox(placeable, template, ctx, refs, () => nat(fitted.width)));
+            const keep = (placed) => {
+                const kept = input.fitBox(frame, placed);
+                if (sameRect(kept, placed))
+                    fitted.delete(frame.name);
+                else
+                    fitted.set(frame.name, { placed, kept });
+                return kept;
+            };
+            const first = keep(r);
+            if (Math.abs(first.width - r.width) < 0.01)
+                return first;
+            return keep(placeBox(placeable, template, ctx, refs, () => nat(first.width)));
         };
         /** A frame's height as its template declares it: its `minHeight` where
          *  the height follows the content, else the content's (`natural`). */
@@ -177,10 +666,13 @@ export function layoutComposedPage(input) {
             return rect;
         };
         /** Lay a group: its frames' boxes as the template declares them and as
-         *  their content needs (`composed/groups.ts`). */
+         *  their content needs (`composed/groups.ts`). With the ladder's
+         *  `redistribute` (#858) every frame gives space back, down to its
+         *  minimum or its content, whether it `shrink`s or not. */
         const placeGroup = (group, members) => {
             const own = groupPlaceable(group);
             const mmPx = dpi / MM_PER_IN;
+            const yieldAll = fit.yieldAll.has(group.name);
             const preps = members.map(prepare);
             const solve = (mode, naturals) => {
                 const refs = mode === 'final' ? refOf : declaredRefOf;
@@ -200,12 +692,13 @@ export function layoutComposedPage(input) {
                     const fill = f.height === 'fill';
                     const minH = f.minHeight ? dimensionToPx(f.minHeight, dpi, input.emPx) : 0;
                     const want = fill ? minH : auto ? (mode === 'final' ? natural(box.width) : declaredNatural(f, natural)(box.width)) : box.height;
-                    return {
+                    const max = f.maxHeight ? dimensionToPx(f.maxHeight, dpi, input.emPx) : Infinity;
+                    const item = {
                         name: f.name,
                         own: box,
                         want,
                         min: minH,
-                        max: f.maxHeight ? dimensionToPx(f.maxHeight, dpi, input.emPx) : Infinity,
+                        max,
                         minWidth: f.minWidth ? dimensionToPx(f.minWidth, dpi, input.emPx) : 0,
                         maxWidth: f.maxWidth ? dimensionToPx(f.maxWidth, dpi, input.emPx) : Infinity,
                         grow: fill ? Math.max(1, f.grow) : f.grow,
@@ -215,6 +708,17 @@ export function layoutComposedPage(input) {
                         fixedHeight: !auto && !fill,
                         need: natural,
                     };
+                    if (yieldAll && mode === 'final' && !f.pin) {
+                        // Down to its minimum, never under what its content needs, never
+                        // over the height it has.
+                        const height = Math.min(Math.max(want, minH), max);
+                        item.shrink = f.shrink > 0 ? f.shrink : 1;
+                        // (A row's frames give width, each down to the narrowest width
+                        // its content still fits: their heights stay the row's.)
+                        if (group.kind === 'stack')
+                            item.min = Math.min(height, Math.max(minH, natural(box.width)));
+                    }
+                    return item;
                 });
                 const firstFree = items.find((it) => !it.pin) ?? items[0];
                 const start = firstFree?.own ?? input.areas.area;
@@ -257,41 +761,59 @@ export function layoutComposedPage(input) {
             groupDeclared.set(group.name, decl.box);
             return fin.rects;
         };
-        /** Pour a frame's content into its box and record the frame. */
+        /** Pour a frame's content into its box and record the frame. A frame
+         *  whose text the ladder scales (#858) is laid out in a box `1 / scale`
+         *  as large, painted at `scale` (`frameMatrix`). */
         const fill = (p, rect) => {
             const { frame, st, holds, continuation, blockId, before } = p;
-            const style = input.styleOf(frame);
+            const style = styleOf(frame);
+            const s = textScale(frame);
+            const pic = pictureScale(frame);
+            const laidW = rect.width / s;
+            const laidH = rect.height / s;
             let result;
             let overflowPx = 0;
+            let goesOn = false;
             const from = st?.cut ?? CUT_START;
             if (holds) {
-                const opts = {
-                    boxHeight: rect.height,
-                    verticalAlign: frame.verticalAlign,
-                    ...(exclusionsFor(frame, rect, false) ? { exclusions: exclusionsFor(frame, rect, false) } : {}),
-                };
-                const whole = st.L.layoutRange(from, st.L.end, rect.width, blockId, continuation, input.mirrored, opts);
+                // What its content needs at its width, measured only when a
+                // proposal asks (`lowerMin`), from where the frame starts.
+                const width = rect.width;
+                const startAt = { ...p, st: { ...st, cut: from } };
+                let known;
+                needs.set(frame.name, () => (known ??= naturalOf(startAt)(width)));
+                const exclusions = unscale(exclusionsFor(frame, rect, false), s);
+                const extra = { ...(exclusions ? { exclusions } : {}), ...(pic !== undefined ? { pictureScale: pic } : {}) };
+                const opts = { boxHeight: laidH, verticalAlign: frame.verticalAlign, ...extra };
+                const whole = st.L.layoutRange(from, st.L.end, laidW, blockId, continuation, input.mirrored, opts);
                 const nextName = nextFrameOf(frame);
                 const nextFrame = nextName !== undefined ? byName.get(nextName) : undefined;
-                if ((whole.overflowPx ?? 0) > 0.5 && nextFrame && !vdtByName.has(nextFrame.name)) {
-                    // The rest goes on in the next frame of the chain.
+                const chained = nextFrame !== undefined && !vdtByName.has(nextFrame.name);
+                // Cut for another page (#859) when the chain ends here.
+                goesOn = !chained && fit.goOn.has(frame.name);
+                if ((whole.overflowPx ?? 0) > 0.5 && (chained || goesOn)) {
+                    // The rest goes on in the next frame of the chain, or on another
+                    // page.
                     const minLines = Math.max(1, style.splitMinLines);
-                    const frag = splitCalloutFragment(pass, st.L, from, rect.width, rect.height, blockId, continuation, minLines, input.mirrored, opts.exclusions ? { exclusions: opts.exclusions } : undefined);
+                    const frag = splitCalloutFragment(pass, st.L, from, laidW, laidH, blockId, continuation, minLines, input.mirrored, extra.exclusions || extra.pictureScale !== undefined ? extra : undefined);
                     const to = frag?.to ?? from;
                     result = frag
-                        ? st.L.layoutRange(from, to, rect.width, blockId, continuation, input.mirrored, opts)
-                        : undefined;
+                        ? st.L.layoutRange(from, to, laidW, blockId, continuation, input.mirrored, opts)
+                        // A styled frame none of whose content fits still draws its box
+                        // (and its mark) when the content goes on elsewhere.
+                        : goesOn && frame.style ? st.L.layoutRange(from, from, laidW, blockId, continuation, input.mirrored, { boxHeight: laidH }) : undefined;
                     st.cut = to;
                 }
                 else {
+                    goesOn = false;
                     result = whole;
-                    overflowPx = whole.overflowPx ?? 0;
+                    overflowPx = (whole.overflowPx ?? 0) * s;
                     st.cut = st.L.end;
                 }
             }
             else if (st && frame.style) {
                 // A styled frame with nothing (left) to hold still draws its box.
-                result = st.L.layoutRange(st.L.end, st.L.end, rect.width, blockId, true, input.mirrored, { boxHeight: rect.height });
+                result = st.L.layoutRange(st.L.end, st.L.end, laidW, blockId, true, input.mirrored, { boxHeight: laidH });
             }
             const vdt = {
                 id: frameIdOf(frame.name),
@@ -300,7 +822,8 @@ export function layoutComposedPage(input) {
                 rotate: frame.rotate,
                 layer: frame.layer,
                 ...(frame.style ? { styleId: frame.style } : {}),
-                scale: 1,
+                scale: s,
+                ...(pic !== undefined && holds ? { imageScale: pic } : {}),
                 overflowPx,
                 blockIds: [],
                 configPath: frame.configPath,
@@ -315,32 +838,49 @@ export function layoutComposedPage(input) {
                 if (q)
                     q.continuesTo = vdt.id;
             }
+            else if (holds && cont?.receivers.has(frame.name)) {
+                // Content from the page before (#859).
+                vdt.continuedFrom = cont.receivers.get(frame.name).fromFrameId;
+            }
             if (result && st) {
                 const range = fragmentRange(st.L, from, st.cut);
                 commitFrame(result, rect, st.story, range, input, vdt, blocks);
                 st.pieces++;
                 st.lastFrameId = vdt.id;
                 laid.add(headOf(frame.name));
+                // What the ladder changed in the frame's content (#858).
+                const pictures = fit.pictures.get(headOf(frame.name));
+                if (pictures && result.children.some((b) => b.type === 'resource')) {
+                    fitLog.push({ frame: frame.name, kind: 'imageScaled', scale: pictures.scale, ...(pictures.by !== frame.name ? { cause: pictures.by } : {}) });
+                }
+                if (s !== 1 && holds)
+                    fitLog.push({ frame: frame.name, kind: 'textScaled', scale: s });
+            }
+            if (goesOn && st) {
+                spills.set(frame.name, { head: headOf(frame.name), cut: st.cut, advanced: !sameCut(from, st.cut), pieces: st.pieces, headBlockId: st.headBlockId, frameId: vdt.id });
             }
             if (overflowPx > 0.5) {
                 const overflowMm = Math.round((overflowPx / dpi) * MM_PER_IN * 10) / 10;
                 overflowLog.push({ frame: frame.name, kind: 'overflow', toMm: overflowMm });
-                warnings.push({
-                    kind: 'frameOverflow',
-                    template: template.id,
-                    frame: frame.name,
-                    fenceIndex: fi,
-                    overflowMm,
-                    configPath: frame.configPath,
-                    ...(vdt.sourceStart !== undefined ? { sourceStart: vdt.sourceStart, sourceEnd: vdt.sourceEnd } : {}),
-                    pageIndex: page.index,
-                });
             }
             if (frame.exclude === 'push') {
                 const box = frameBounds({ rect, rotate: frame.rotate });
                 pushRects.set(frame.name, box);
+                // `wrap: 'contour'` (#883): the shape of the pictures it holds; a
+                // turned frame pushes with its box.
+                const shape = frame.wrap === 'contour' && frame.rotate === 0 && result
+                    ? frameContour(result.children, { gapPx: input.pushGapPx, dpi, emPx: input.emPx, mirrored: pageIsMirrored(input.page), pageIndex: input.page.index })
+                    : undefined;
+                if (shape)
+                    notes.push(...shape.notes);
+                // A frame whose text the ladder scaled (#858) holds its pictures in
+                // its laid-out coordinates: on the page they are `s` as large, from
+                // its box's corner (`frameMatrix`).
+                const contour = shape?.contour && s !== 1 ? scaleContourAbout(shape.contour, rect.x, rect.y, s, false) : shape?.contour;
+                if (contour)
+                    pushShapes.set(frame.name, contour);
                 if (!seed)
-                    pushed.push({ name: frame.name, box });
+                    pushed.push({ name: frame.name, box, ...(contour ? { contour } : {}) });
             }
             frames.push(vdt);
             vdtByName.set(frame.name, vdt);
@@ -357,29 +897,12 @@ export function layoutComposedPage(input) {
             for (const f of step.frames)
                 fill(prepare(f), solved.get(f.name));
         }
-        const log = mergeLog(reflowEvents(motionsOf(template, rects, declared), dpi / MM_PER_IN), overflowLog, template);
-        return { frames, blocks, warnings, log, laid, pushRects };
+        const log = mergeLog(reflowEvents(motionsOf(template, rects, declared), dpi / MM_PER_IN), [...fitLog, ...overflowLog], template);
+        return { frames, blocks, log, laid, needs, pushRects, pushShapes, fitted, notes, spills };
     };
     const first = run();
-    const { frames, blocks, warnings, log, laid } = first.pushRects.size > 0 ? run(first.pushRects) : first;
-    // Template order on the page record.
-    const order = new Map(template.frames.map((f, i) => [f.name, i]));
-    frames.sort((a, b) => order.get(a.name) - order.get(b.name));
-    const contentBlocks = pass.contentBlocks;
-    const composed = {
-        template: template.id,
-        ...(template.variant ? { variant: template.variant } : {}),
-        fenceIndex: fi,
-        role: template.role,
-        attrs: { ...fence.attrs },
-        attrSources: Object.fromEntries(Object.entries(fence.attrSources).map(([k, v]) => [k, { sourceStart: v.sourceStart + input.bodyOffset, sourceEnd: v.sourceEnd + input.bodyOffset }])),
-        frames,
-        log,
-        configPath: template.configPath,
-        sourceStart: contentBlocks[input.startIdx].sourceStart + input.bodyOffset,
-        sourceEnd: contentBlocks[input.endIdx].sourceEnd + input.bodyOffset,
-    };
-    return { composed, blocks, warnings, laid };
+    const { frames, blocks, log, laid, needs, fitted, notes, spills } = first.pushRects.size > 0 ? run(first.pushRects, first.pushShapes) : first;
+    return { frames, blocks, log, laid, needs, template, fitted, spills, ...(notes.length > 0 ? { notes } : {}) };
 }
 const sameRect = (a, b) => Math.abs(a.x - b.x) < 0.01 && Math.abs(a.y - b.y) < 0.01 && Math.abs(a.width - b.width) < 0.01 && Math.abs(a.height - b.height) < 0.01;
 /** Each laid frame's declared and final boxes, in template order, with
@@ -439,6 +962,7 @@ function commitFrame(result, rect, story, range, input, vdt, out) {
     }
     box.pageIndex = page.index;
     box.columnIndex = 0;
+    stampFrameAttrText(box, blocks[story.startIdx]?.containerAttrSources, story.plan.attrs, bodyOffset);
     offsetCalloutToAbsolute(result, rect.x, rect.y);
     out.push(box);
     vdt.blockIds.push(box.id);
@@ -449,6 +973,37 @@ function commitFrame(result, rect, story, range, input, vdt, out) {
         vdt.blockIds.push(child.id);
     }
 }
+/** The frame's tab (`label`) and title (`title`) as the box draws them,
+ *  stamped with where the `:::frame` fence writes them (#857): the
+ *  attribute's value range, and a per-character map when the text is
+ *  printed as written. */
+function stampFrameAttrText(box, sources, attrs, bodyOffset) {
+    if (!sources || !box.designOverlay)
+        return;
+    for (const name of ['label', 'title']) {
+        const src = sources[name];
+        const value = attrs[name];
+        if (!src || value === undefined || value.trim() === '')
+            continue;
+        const start = src.sourceStart + bodyOffset;
+        const end = src.sourceEnd + bodyOffset;
+        for (const b of box.designOverlay.blocks) {
+            if (b.kind !== 'text' || b.attr !== undefined)
+                continue;
+            const shown = b.lines.map((l) => l.text).join(' ');
+            if (shown.trim() !== value.trim() && shown.trim().toLocaleLowerCase() !== value.trim().toLocaleLowerCase())
+                continue;
+            b.sourceStart = start;
+            b.sourceEnd = end;
+            b.attr = name;
+            if (shown === value && end - start === value.length) {
+                b.sourceText = value;
+                b.sourceMap = Array.from({ length: value.length }, (_, i) => start + i);
+            }
+            break;
+        }
+    }
+}
 /** The callout style a frame is drawn with: `base` (its `style`, or the
  *  frameless frame style) with what a frame sets of its own: its padding
  *  (side by side) and a measure that is the frame's. A style's placement,