@quario/pdf 0.2.0 → 0.4.0

package/lib/layout.js

@@ -1,1663 +0,0 @@
-/**
- * Laying the event stream out on pages: items flow as wrapped blocks, tables
- * are measured whole and emitted row by row with the header replayed after
- * every break, and group headers wait for the content they introduce and then
- * travel with it — a page a group instance continues onto opens with the same
- * headers the page that introduced it did.
- *
- * Page state is the drawing surface's (`canvas.js`), so most of what follows
- * takes a `Canvas` and nothing else. Pagination is the exception, and honestly
- * so: `turn`, `item` and the table's `Grid` take the flow, because a page turn
- * is now the moment the open groups get their headers back. What stays here is
- * the band flow's own bookkeeping — the headers still waiting, the ones a turn
- * replays, the space owed before the next group instance, and the outline marks
- * it anchors as it goes. `flow` at the foot of the file is what owns that
- * record: it hands out every handler a render walks the stream through, and a
- * `finish` that flushes what is left.
- * Nothing else can reach them, and no caller adds a handler of its own, so the
- * order those handlers impose is not an order a caller can get wrong.
- *
- * Page furniture is here too, both halves of it: how much of the page a
- * document's bands claim before anything is placed, and where they are drawn
- * on each finished page once the count is known.
- */
-import { display, isReportBand, text } from "quario";
-import { balance } from "./balance.js";
-import { adopt, frame, measuring } from "./canvas.js";
-import { intrinsic } from "./image.js";
-import { BAND, GUTTER, LEAD, PADX, PADY, col, roled, shift, sizeOf, stack } from "./style.js";
-import { atoms, dress, heightOf, wrap } from "./text.js";
-
-/** @typedef {import('./balance.js').Unit} Unit */
-/** @typedef {import('./canvas.js').Canvas} Canvas */
-/** @typedef {import('./canvas.js').Frame} Frame */
-/** @typedef {import('./text.js').Line} Line */
-
-// `open` is a stack, one entry per group instance still open: the header items
-// it holds back until content arrives, and — once those are drawn — the blocks
-// a page turn replays them from. `gap` is the space owed before the next group
-// instance, `marks` the outline entries, which `anchor` positions from the
-// cursor, and `starts` the page indexes where a `reset: "page"` sequence
-// begins (the document itself is the sequence that starts at page 0).
-/**
- * @typedef {{ held: any[], blocks: Block[] }} Group
- */
-/**
- * @typedef {{ canvas: Canvas, open: Group[], gap: number, marks: any[],
- *   starts: number[], region: Region | null, pending: Pending | null,
- *   measured: WeakMap<any, Measured>,
- *   route: (event: any, block?: Block | null) => void }} Flow
- */
-
-// One flow unit and its presentation; `h` is the full flow height. A text
-// item's is its wrapped lines; an image item's is the picture, sized here so
-// everything downstream -- fitting, holding a group header back, replaying it
-// on a continued page -- reads one height and never a second kind of unit.
-/**
- * @typedef {{ bytes: Uint8Array, format: string, w: number, h: number }} Picture
- */
-/**
- * `align` is absent on a split, which has none of its own: alignment is a
- * slot's, reached through the style layering.
- * @typedef {{ lines: Line[], picture?: Picture, parts?: SlotPart[],
- *   bg: string | null, align?: any, h: number }} Block
- */
-/**
- * One slot of a split, as laid out: the block it drew to and the width it was
- * measured at. There is no offset — a slot's is the sum of the widths before
- * it, which `drawSplit` accumulates as it walks them.
- * @typedef {{ block: Block, w: number }} SlotPart
- */
-
-// How `fit` sizes a picture against the width it has: `natural` is the
-// image's own size in points, never wider than the content box; `width`
-// scales to the content box either way. The ratio is kept in both, so a
-// height is never anything but the width's consequence.
-/** @type {(event: any, avail: number) => Picture} */
-let pictureOf = (event, avail) => {
-  let { w, h } = intrinsic(event.bytes, event.format);
-  let width = event.fit === "width" ? avail : Math.min(w, avail);
-  return { bytes: event.bytes, format: event.format, w: width, h: (h * width) / w };
-};
-
-// `under` is the enclosing style a slot's own layers over — a split's, when
-// this is one of its slots. Null everywhere else, where nothing encloses.
-/** @type {(canvas: Canvas, event: any, avail: number, under?: any) => Block} */
-let blockOf = (canvas, event, avail, under = null) => {
-  let style = stack(canvas, under, event.style);
-  let bg = col(style.background);
-  if (event.type === "split") return splitBlock(canvas, event, avail, style, bg);
-  if (event.type === "image") {
-    let picture = pictureOf(event, avail);
-    return { lines: [], picture, bg, align: style.align, h: picture.h };
-  }
-  let lines = dress(wrap(canvas, atoms(canvas, event.tokens, style), Math.max(avail, 1)), style);
-  return { lines, bg, align: style.align, h: heightOf(lines) };
-};
-
-// Scale a picture block down to the room it has. Best-effort, and only ever
-// reached by an image no page could hold whole (SCHEMA.md).
-/** @type {(block: Block, room: number) => void} */
-let shrink = (block, room) => {
-  let picture = /** @type {Picture} */ (block.picture);
-  picture.w *= room / picture.h;
-  picture.h = room;
-  block.h = room;
-};
-
-// Draw one block whole at the cursor. A picture's background fills the
-// image's own box rather than the width of the flow -- there is no line for
-// it to sit behind. Text is placed line by line as each is drawn; a picture
-// is one box, so where it sits in the width it was given is worked out once.
-/** @type {(canvas: Canvas, block: Block, x: number, avail: number) => void} */
-let drawPicture = (canvas, block, x, avail) => {
-  let { bytes, format, w, h } = /** @type {Picture} */ (block.picture);
-  let at = x + shift(block.align, avail - w);
-  if (block.bg) canvas.rect(block.bg, at, canvas.y - h, w, h);
-  canvas.picture(bytes, format, at, canvas.y - h, w, h);
-  canvas.y -= h;
-  canvas.fresh = false;
-};
-
-/** @type {(canvas: Canvas, block: Block, x: number, avail: number) => void} */
-let drawLines = (canvas, block, x, avail) => {
-  if (block.bg) canvas.rect(block.bg, x, canvas.y - block.h, avail, block.h);
-  for (let line of block.lines) {
-    canvas.drawLine(line, x, canvas.y, avail, block.align);
-    canvas.y -= line.h;
-  }
-  canvas.fresh = false;
-};
-
-// An authored share fixes its slot; the width-less ones divide what is left,
-// evenly. Evenly rather than by natural width, because a split is a line of
-// furniture whose geometry should read off the document — the same answer the
-// HTML target's `flex:1` gives, so one definition places alike in both.
-// Each slot is measured at its own share and drawn from a common top, so the
-// split is as tall as its tallest slot and the line's geometry does not move
-// with the data. The split's own declarations are the layer under each slot's,
-// so a split styled `bold` reads the same here as it does through CSS
-// inheritance in the HTML target and the `under` layer in XLSX. It has no
-// `align` of its own: alignment is a slot's, reached through that layering.
-/**
- * @type {(canvas: Canvas, event: any, avail: number, style: any,
- *   bg: string | null) => Block}
- */
-let splitBlock = (canvas, event, avail, style, bg) => {
-  let widths = slotWidths(event.slots, avail);
-  /** @type {SlotPart[]} */
-  let parts = [];
-  let h = 0;
-  for (let [i, slot] of event.items.entries()) {
-    let block = blockOf(canvas, slot, Math.max(widths[i], 1), style);
-    if (block.h > h) h = block.h;
-    parts.push({ block, w: widths[i] });
-  }
-  return { lines: [], parts, bg, h };
-};
-
-/** @type {(slots: { width?: number }[], avail: number) => number[]} */
-let slotWidths = (slots, avail) => {
-  let autos = 0,
-    spent = 0;
-  /** @type {(number | null)[]} */
-  let fixed = slots.map(({ width }) => {
-    // Bound to a local first: `Number.isFinite` does not narrow a property.
-    if (width === undefined || !Number.isFinite(width)) return (autos++, null);
-    let share = (width / 100) * avail;
-    spent += share;
-    return share;
-  });
-  let each = autos ? Math.max(avail - spent, 0) / autos : 0;
-  return fixed.map((width) => width ?? each);
-};
-
-// A split reaches this target as a bracket around ordinary item and image
-// events. Folding it into one event is what lets the rest of the target treat
-// it as a single block -- measured, kept together, and paged by exactly the
-// machinery every other block goes through. Stateful rather than a transform
-// over an array, because the body walk is streaming; the page-band pass drives
-// the same folder over its own list, so the two cannot drift.
-// The event types that become a `Block`. They are also exactly the three the
-// split folder owns: item and image reach `route` through it, so a slot's are
-// collected rather than placed, and `split` is minted by the folder and never
-// arrives from the stream at all.
-let BLOCKS = new Set(["item", "image", "split"]);
-
-/** @type {(emit: (event: any) => void) => (event: any) => void} */
-let splitFolder = (emit) => {
-  /** @type {{ event: any, items: any[] } | null} */
-  let bracket = null;
-  // The engine emits the bracket as one array, so `split-end` always has its
-  // opening and this never reads a null.
-  let close = () => {
-    let { event, items } = /** @type {{ event: any, items: any[] }} */ (bracket);
-    bracket = null;
-    emit({ type: "split", role: event.role, style: event.style, slots: event.slots, items });
-  };
-  return (event) => {
-    if (event.type === "split-start") bracket = { event, items: [] };
-    else if (event.type === "split-end") close();
-    else if (bracket) bracket.items.push(event);
-    else emit(event);
-  };
-};
-
-/** @type {(canvas: Canvas, block: Block, x: number, avail: number) => void} */
-let drawSplit = (canvas, block, x, avail) => {
-  if (block.bg) canvas.rect(block.bg, x, canvas.y - block.h, avail, block.h);
-  let top = canvas.y;
-  let at = x;
-  for (let part of block.parts || []) {
-    canvas.y = top;
-    drawBlock(canvas, part.block, at, part.w);
-    at += part.w;
-  }
-  // The split takes its own height whatever the slots took, so a short slot
-  // beside a wrapped one does not pull the band up.
-  canvas.y = top - block.h;
-  canvas.fresh = false;
-};
-
-/** @type {(canvas: Canvas, block: Block, x: number, avail: number) => void} */
-let drawBlock = (canvas, block, x, avail) =>
-  (block.parts ? drawSplit : block.picture ? drawPicture : drawLines)(canvas, block, x, avail);
-
-// A region is a run of strips: what a columned node's content flows down
-// (CONTEXT.md "Strip"). `index` is the strip being filled, `top` the y every
-// strip on this page starts from, `ends` where the finished ones stopped, and
-// `floor` the bottom the current strip fills to — the page bottom while
-// filling, a shorter target while balancing. `owner` is the depth of the group
-// that declared the count, or -1 for the report root.
-/**
- * @typedef {{ width: number, count: number, index: number, top: number,
- *   height: number | null, ends: number[], owner: number,
- *   held: any[] | null, measured: number }} Region
- */
-/**
- * @typedef {{ count: number, owner: number }} Pending
- */
-
-// Where the cursor's column starts and how wide it is: the strip's, inside a
-// region, and the page's content box outside one. Every drawing call reads
-// these rather than `canvas.margin`/`canvas.content` — the canvas keeps
-// presenting the page, because `pageBox` re-derives page furniture from it.
-/** @type {(state: Flow) => number} */
-let originOf = (state) =>
-  state.canvas.margin + (state.region ? state.region.index * (state.region.width + GUTTER) : 0);
-/** @type {(state: Flow) => number} */
-let widthOf = (state) => (state.region ? state.region.width : state.canvas.content);
-// The bottom the cursor fills to. A balanced strip's floor sits above the page
-// bottom and is a target rather than a bound: a fresh strip still takes at
-// least one line, so a block that fits the page is placed even where it
-// overruns. The last strip answers to the page instead — a balanced share is
-// rounded, so the strips before it may each stop a little short, and the
-// remainder has to land somewhere.
-/** @type {(state: Flow) => number} */
-let floorOf = (state) => {
-  let region = state.region;
-  if (!region || region.height == null || region.index === region.count - 1)
-    return state.canvas.bottom;
-  return region.top - region.height;
-};
-// The y a fresh column starts from: a strip's shared top inside a region.
-/** @type {(state: Flow) => number} */
-let ceilOf = (state) => (state.region ? state.region.top : state.canvas.top);
-// Has this column taken anything yet? Answered positionally, because the only
-// thing that marks a page used is the cursor moving off its top, and the
-// drawing primitives that move it take a `Canvas` rather than a `Flow`.
-// `canvas.fresh` stays the *page*'s own answer — it is what keeps `turn` from
-// leaving an empty page behind — so a strip claims no second meaning for it.
-// A block of no height would read fresh here and used there; none is reachable
-// today, since every item wraps to at least one line.
-/** @type {(state: Flow) => boolean} */
-let freshOf = (state) => (state.region ? state.canvas.y === state.region.top : state.canvas.fresh);
-
-/** @type {(canvas: Canvas, h: number, line: Line, floor: number) => boolean} */
-let hasRoom = (canvas, h, line, floor) => canvas.y - h - line.h >= floor;
-
-// A fresh column always takes at least one line, or nothing would ever fit —
-// which is also what makes a balanced floor a target rather than a bound.
-/** @type {(fresh: boolean, j: number, i: number) => boolean} */
-let takeLine = (fresh, j, i) => j === i && fresh;
-
-/**
- * @type {(canvas: Canvas, lines: Line[], i: number, floor: number,
- *   fresh: boolean) => { j: number, h: number }}
- */
-let grow = (canvas, lines, i, floor, fresh) => {
-  let j = i,
-    h = 0,
-    n = lines.length;
-  while (j < n) {
-    if (!hasRoom(canvas, h, lines[j], floor) && !takeLine(fresh, j, i)) break;
-    h += lines[j++].h;
-  }
-  return { j, h };
-};
-
-/** @type {(n: number, j: number, i: number) => boolean} */
-let orphan = (n, j, i) => n - j === 1 && j - i >= 2;
-
-/** @type {(i: number, j: number, n: number, fresh: boolean) => boolean} */
-let widow = (i, j, n, fresh) => i === 0 && j - i === 1 && n >= 2 && !fresh;
-
-// Never leave a single line behind (an orphan) or take one across alone
-// (a widow): give one back, or move the whole block down.
-/**
- * @type {(lines: Line[], i: number, j: number, h: number,
- *   fresh: boolean) => { j: number, h: number }}
- */
-let mend = (lines, i, j, h, fresh) => {
-  let n = lines.length;
-  if (j >= n) return { j, h };
-  if (orphan(n, j, i)) h -= lines[--j].h;
-  if (widow(i, j, n, fresh)) j = i;
-  return { j, h };
-};
-
-// Lines `i..j` fit in this column, occupying height `h`; `j === i` means the
-// column is spent.
-/**
- * @type {(canvas: Canvas, block: Block, i: number, floor: number,
- *   fresh: boolean) => { j: number, h: number }}
- */
-let fitLines = (canvas, block, i, floor, fresh) => {
-  let { j, h } = grow(canvas, block.lines, i, floor, fresh);
-  return mend(block.lines, i, j, h, fresh);
-};
-
-/** @type {(canvas: Canvas, block: Block, floor: number) => boolean} */
-let whole = (canvas, block, floor) => canvas.y - block.h >= floor;
-
-// The unsplittable blocks -- a picture and a split -- move whole to a fresh
-// column rather than breaking, so a balanced floor never cuts one: only the
-// page's own floor bears on it. A picture that no column can hold is scaled
-// down to the one it lands on, since obeying the guarantee literally would
-// mean dropping it (SCHEMA.md, best-effort); a split has nothing to scale, so
-// one taller than any column renders in full past the bottom margin, the
-// posture a paragraph line taller than a page already has.
-//
-// A split also *cannot* be sliced: its own `lines` are empty -- the content
-// lives in its slots -- so the slicing path would draw nothing and leave the
-// cursor where it stood, taking everything after it down with it.
-/** @type {(state: Flow, block: Block) => void} */
-let placeWhole = (state, block) => {
-  advance(state);
-  let canvas = state.canvas;
-  let room = canvas.y - canvas.bottom;
-  if (block.picture && block.h > room) shrink(block, room);
-  drawBlock(canvas, block, originOf(state), widthOf(state));
-};
-
-/**
- * @type {(canvas: Canvas, block: Block, x: number, avail: number, lines: Line[],
- *   i: number, j: number, h: number) => number}
- */
-let fillSlice = (canvas, block, x, avail, lines, i, j, h) => {
-  if (block.bg) canvas.rect(block.bg, x, canvas.y - h, avail, h);
-  while (i < j) {
-    canvas.drawLine(lines[i], x, canvas.y, avail, block.align);
-    canvas.y -= lines[i++].h;
-  }
-  canvas.fresh = false;
-  return i;
-};
-
-/** @type {(state: Flow, block: Block, lines: Line[], i: number, n: number) => number} */
-let paintSlice = (state, block, lines, i, n) => {
-  let canvas = state.canvas;
-  let { j, h } = fitLines(canvas, block, i, floorOf(state), freshOf(state));
-  if (j === i) {
-    advance(state);
-    return i;
-  }
-  i = fillSlice(canvas, block, originOf(state), widthOf(state), lines, i, j, h);
-  if (i < n) advance(state);
-  return i;
-};
-
-/** @type {(state: Flow, block: Block) => void} */
-let slice = (state, block) => {
-  let lines = block.lines,
-    n = lines.length,
-    i = 0;
-  while (i < n) i = paintSlice(state, block, lines, i, n);
-};
-
-// Flow a block down the column, breaking where `fitLines` says. Each slice
-// paints its background before its lines.
-/** @type {(state: Flow, event: any, measured?: Block | null) => void} */
-let item = (state, event, measured = null) => {
-  let canvas = state.canvas;
-  let avail = widthOf(state);
-  let block = measured || blockOf(canvas, event, avail);
-  // Whole block fits where it stands: one piece, no slicing.
-  if (whole(canvas, block, floorOf(state))) return drawBlock(canvas, block, originOf(state), avail);
-  overflow(state, block);
-};
-
-// What a block does when it does not fit where it stands. A picture and a
-// split never break -- each moves whole to a fresh column; anything else flows
-// down it, breaking where `fitLines` says.
-/** @type {(state: Flow, block: Block) => void} */
-let overflow = (state, block) =>
-  block.picture || block.parts ? placeWhole(state, block) : slice(state, block);
-
-// The height a page turn carries over: the drawn headers of the groups still
-// open, which every page their instances continue onto replays. Computed rather
-// than kept — a stored total is a second copy of `open` that can drift from it.
-// Never "running": CONTEXT.md spends that word on the accumulators under `run`.
-//
-// What a page has left after it is what `flush` measures a run against, so a
-// repeat always leaves room for the content unit it introduces. That room is
-// measured from the group's *first* unit, though: a later item with lines
-// taller than what is left is drawn past the bottom margin all the same, as a
-// line taller than a page always was. SCHEMA.md says so rather than guarding
-// it — the alternative is dropping content.
-/** @type {(state: Flow) => number} */
-let carried = (state) =>
-  state.open.reduce(
-    (total, group) => total + group.blocks.reduce((height, block) => height + block.h, 0),
-    0,
-  );
-
-// Break unless the page is still fresh, where a turn would only leave an empty
-// page behind. Every break goes through here — the elective ones and the
-// overflows alike — because a fresh page owes the open groups their headers
-// back, and one owner for that is one place to get it right.
-//
-// The replayed run is not content, and `fresh` stays true across it: that is
-// what keeps `fitLines` taking at least one line here (so a run of turns always
-// advances), keeps `put` from breaking straight back out, and keeps a second
-// turn a no-op. The blocks are the ones `flush` drew, repainted exactly as
-// `carryOver` repaints a table's header row — `adopt` moves only the top and
-// bottom, so the content width is fixed for the render and a block measured on
-// page one is valid on page nine.
-/** @type {(state: Flow) => void} */
-let turn = (state) => {
-  let canvas = state.canvas;
-  if (canvas.fresh) return;
-  canvas.newPage();
-  replayOpen(state);
-  canvas.fresh = true;
-  if (state.region) restrip(state.region, canvas.y);
-};
-
-// What a fresh page owes the instances still open: their drawn headers again.
-// Under a region the replay goes into the first strip, at the width the blocks
-// were measured at — they are the region's content continuing, not page
-// furniture, and drawing them across the page would straddle every strip below
-// them. The strips then restart under the run.
-/** @type {(state: Flow) => void} */
-let replayOpen = (state) => {
-  if (state.region) state.region.index = 0;
-  let x = originOf(state),
-    avail = widthOf(state);
-  for (let group of state.open)
-    for (let block of group.blocks) drawBlock(state.canvas, block, x, avail);
-};
-
-// Every strip on a page shares a top and, while balancing, a floor. Reset
-// together so a page turn and a region opening say the same thing once.
-/** @type {(region: Region, top: number) => void} */
-let restrip = (region, top) => {
-  region.index = 0;
-  region.top = top;
-  region.ends = [];
-};
-
-// The column break: move to the next strip, and only turn the page once the
-// last one is spent. Outside a region this is a page turn and nothing else,
-// which is why every break in this file goes through here.
-/** @type {(state: Flow) => void} */
-let advance = (state) => {
-  let region = state.region;
-  if (!region) return turn(state);
-  // Nothing in this column yet: advancing would leave it empty and the next
-  // one would refuse the same block, so the caller must place it here.
-  if (freshOf(state)) return;
-  region.ends.push(state.canvas.y);
-  if (region.index + 1 < region.count) {
-    region.index++;
-    state.canvas.y = region.top;
-    return;
-  }
-  // Spent: a real page, which restrips through `turn`.
-  turn(state);
-};
-
-// --- regions ----------------------------------------------------------------
-
-// One strip's width: the content box less the gutters, shared out. Needed
-// before a region exists, because a keep-with block is measured against the
-// width the item is about to land in.
-/** @type {(state: Flow, count: number) => number} */
-let stripWidth = (state, count) => (state.canvas.content - GUTTER * (count - 1)) / count;
-
-// Open the region a `columns` count owed, at the first content that belongs in
-// it. Deferred to here rather than opened where the count arrived, because the
-// declaring node's own header run is full-width and has to be drawn first —
-// `flush` does that immediately above every call site.
-//
-// It opens buffering: what the strips do with the content depends on how much
-// of it there is, and that is not known until the region ends or outgrows a
-// page. `held` is that buffer; `null` means the region has committed.
-/** @type {(state: Flow) => void} */
-let openRegion = (state) => {
-  let owed = state.pending;
-  if (!owed || state.region) return;
-  state.pending = null;
-  let canvas = state.canvas;
-  state.region = {
-    width: stripWidth(state, owed.count),
-    count: owed.count,
-    index: 0,
-    top: canvas.y,
-    height: null,
-    ends: [],
-    owner: owed.owner,
-    held: [],
-    measured: 0,
-  };
-};
-
-// Close the region: the cursor lands at whichever strip reached lowest, and
-// full-width content resumes under it on the same page (SCHEMA.md).
-/** @type {(state: Flow) => void} */
-let closeRegion = (state) => {
-  let region = state.region;
-  if (!region) return;
-  // Committing replays the buffer, and a replayed footer closes the region on
-  // its own way through — so re-read rather than trusting the local.
-  if (region.held) commit(state);
-  if (!state.region) return;
-  let canvas = state.canvas;
-  canvas.y = Math.min(canvas.y, ...region.ends);
-  state.region = null;
-};
-
-// The region's own entries as the things a strip places (`balance.js`). Only
-// text flows; a group instance, a table's headings row, a table row and an
-// image all move whole, and `head` is where each says what it costs when it is
-// the first thing in a strip: an instance drops its opening gap there, a row
-// pays for the column headings the table restates above it, and the other two
-// cost the same wherever they land.
-//
-// Two things this deliberately does not model, each stated because the cost of
-// getting them wrong is a strip that stops early rather than a wrong document.
-// A `total-row` is a row like any other, though it really keeps the last data
-// row with it (SCHEMA.md): pairing them costs the flat per-entry map this is,
-// to remove an error of one row at the end of a table. And a row taller than
-// any strip is sliced rather than moved (SCHEMA.md, "How a tall row slices");
-// called whole here, it makes every candidate height fail and the region
-// fills, which is the honest answer for a region holding one.
-//
-// Row heights themselves are real, not the buffer's one-line estimate —
-// `remeasure` corrects them when the table closes.
-/** @type {(state: Flow, own: any[]) => Unit[]} */
-let unitsOf = (state, own) => {
-  let table = { headings: 0 };
-  return own.map((entry) => unitFor(state.canvas, entry, table));
-};
-
-// What the open table costs a strip that has to restate it, carried between
-// entries because a row is what pays for the headings and a row cannot see
-// them.
-/**
- * @typedef {{ headings: number }} Restated
- */
-// One entry's cost, by what it is.
-/** @type {(canvas: Canvas, entry: any, table: Restated) => Unit} */
-let unitFor = (canvas, entry, table) => {
-  if (entry.span != null) return unsplit(entry.span, headOf(canvas, entry.span));
-  return (UNITS[entry.event.type] || flows)(entry, table);
-};
-
-/** @type {(h: number, head: number) => Unit} */
-let unsplit = (h, head) => ({ whole: true, h, head });
-/** @type {(entry: any) => Unit} */
-let flows = (entry) => ({ whole: false, h: entry.h, head: entry.h });
-
-// What each kind of entry that does not flow costs. A module constant for the
-// reason `WORTH` is one: this runs once per buffered entry. It is not `WORTH`
-// with more names — that answers what an event adds to the running total when
-// it carries no block, so it holds `group-start` (whose gap nothing else
-// counts) and no `image` (which always carries one).
-/** @type {Record<string, (entry: any, table: Restated) => Unit>} */
-let UNITS = {
-  // The headings row is a unit itself, and opening the table is where what a
-  // later strip owes for restating it is recorded.
-  "table-start": (entry, table) => {
-    table.headings = entry.h;
-    return unsplit(entry.h, entry.h);
-  },
-  row: restated,
-  "total-row": restated,
-  image: unbroken,
-  split: unbroken,
-};
-
-// An unsplittable block owes a strip nothing but its own height.
-/** @type {(entry: any) => Unit} */
-function unbroken(entry) {
-  return unsplit(entry.h, entry.h);
-}
-
-// A row opening a strip carries the column headings restated above it.
-/** @type {(entry: any, table: Restated) => Unit} */
-function restated(entry, table) {
-  return unsplit(entry.h, entry.h + table.headings);
-}
-
-// The one number the buffer decides. A region that fits a page balances — the
-// shortest strip height that still holds its units in `count` strips — and a
-// longer one, or one no such height exists for, fills each strip to the page
-// bottom. Filling is the taller floor of the two, so committing to it is
-// committing to nothing: the strips simply take what they take.
-/** @type {(state: Flow, region: Region, own: any[]) => number | null} */
-let stripHeight = (state, region, own) =>
-  outgrown(state, region)
-    ? null
-    : balance(unitsOf(state, own), region.count, roomOf(state, region), rowHeight(state.canvas));
-
-/** @type {(state: Flow) => void} */
-let commit = (state) => {
-  let region = /** @type {Region} */ (state.region);
-  let held = /** @type {any[]} */ (region.held);
-  // Marking the spans is also what picks out the region's own children, and
-  // the height is decided from those — so it runs before the replay, not with
-  // it.
-  region.height = stripHeight(state, region, spans(held));
-  region.held = null;
-  restrip(region, region.top);
-  for (let entry of held) {
-    if (breaksFor(state, region, entry.span)) advance(state);
-    state.route(entry.event, entry.block);
-  }
-};
-
-// A group instance is the atomic unit inside a region: one that would cross a
-// strip boundary, and would fit a strip of its own, opens the next one
-// instead. An instance no strip can hold answers false and continues, the way
-// anything too tall does (SCHEMA.md). What a fresh strip has to hold is the
-// span less the opening gap, which `settle` drops at a strip head — the same
-// unit `balance.js` packs. Only a buffered `group-start` carries a span;
-// everything else flows.
-/** @type {(state: Flow, region: Region, span: number | undefined) => boolean} */
-let breaksFor = (state, region, span) =>
-  span != null &&
-  !freshOf(state) &&
-  state.canvas.y - span < floorOf(state) &&
-  headOf(state.canvas, span) <= roomOf(state, region);
-
-// How much one strip of this region can hold, and whether the buffer has more
-// than every strip together could take. The balance-or-fill decision and the
-// early commit that gives up on balancing are the same question, so they are
-// the same predicate.
-/** @type {(state: Flow, region: Region) => number} */
-let roomOf = (state, region) => region.top - state.canvas.bottom;
-/** @type {(state: Flow, region: Region) => boolean} */
-let outgrown = (state, region) => region.measured > roomOf(state, region) * region.count;
-
-// Mark every buffered `group-start` with the height of the instance it opens,
-// so the replay can keep it whole. Only the region's own children carry one:
-// an inner instance is held by the outer one it belongs to.
-//
-// The empty stack is also what says an entry is the region's own child, so the
-// same walk hands those back — one traversal answers both questions rather
-// than two tracking the same nesting.
-/** @type {(held: any[]) => any[]} */
-let spans = (held) => {
-  /** @type {number[]} */
-  let stack = [];
-  /** @type {any[]} */
-  let own = [];
-  for (let [i, entry] of held.entries()) {
-    if (!stack.length) own.push(entry);
-    nest(held, stack, entry, i);
-    if (stack.length) held[stack[0]].span += entry.h;
-  }
-  return own;
-};
-
-// Track the instance nesting one entry at a time. Only the outermost one open
-// carries a span, which is what makes it the region's own child.
-/** @type {(held: any[], stack: number[], entry: any, i: number) => void} */
-let nest = (held, stack, entry, i) => {
-  if (entry.event.type === "group-end") return void stack.pop();
-  if (entry.event.type !== "group-start") return;
-  if (!stack.length) held[i].span = 0;
-  stack.push(i);
-};
-
-// What a buffered event is worth to the running total when it carries no block
-// of its own: a table row and a group's opening gap are the two that matter,
-// and both are known without laying anything out.
-/** @type {(state: Flow, event: any) => number} */
-let estimate = (state, event) => (WORTH[event.type] || (() => 0))(state.canvas);
-
-// What each kind of buffered event is worth. A module constant: `estimate` runs
-// once per buffered event, and rebuilding this table each time would allocate
-// a closure per table row.
-/** @type {Record<string, (canvas: Canvas) => number>} */
-let WORTH = {
-  row: (canvas) => rowHeight(canvas) + 2 * PADY,
-  "total-row": (canvas) => rowHeight(canvas) + 2 * PADY,
-  "table-start": (canvas) => rowHeight(canvas) + 2 * PADY,
-  "group-start": (canvas) => instanceGap(canvas),
-};
-
-// Buffer one event while the region is still deciding, keeping a running total
-// of what it holds. A measured block rides along so the replay never wraps the
-// same text twice; a held header counts towards the total like anything else,
-// but the flush that draws it measures from the event, so only its height is
-// kept. A buffer that outgrows what the strips could hold has answered the
-// question early: it commits to filling, and everything after it streams.
-/** @type {(state: Flow, event: any, block: Block | null) => void} */
-let buffer = (state, event, block) => {
-  let region = /** @type {Region} */ (state.region);
-  let entry = entryFor(state, event, block, region.width);
-  /** @type {any[]} */ (region.held).push(entry);
-  region.measured += entry.h;
-  if (event.type === "table-end") region.measured += remeasure(state, region);
-  if (outgrown(state, region)) commit(state);
-};
-
-// A table's events reach the buffer one at a time, and each is worth a bare
-// estimate — one line — until the table closes: a row's height is what its
-// cells wrap to, that needs the column widths, and those need every cell in
-// the table. The last event is where the table is finally in hand, so it is
-// measured at the strip width and its entries are corrected. Both readers of
-// those heights want the real ones: the balance model, and `outgrown`.
-//
-// The replay measures the table again when it draws it. That is the price of
-// keeping `table` the one place a table is laid out, and it is paid once per
-// table per render.
-// The measurement is kept, keyed by the opening event, so the replay draws
-// this table without wrapping every cell a second time. Held per flow rather
-// than per module: the keys are one render's events.
-/** @type {(state: Flow, region: Region) => number} */
-let remeasure = (state, region) => {
-  let held = /** @type {any[]} */ (region.held);
-  let at = held.findLastIndex((entry) => entry.event.type === "table-start");
-  if (at < 0) return 0;
-  let span = held.slice(at);
-  let measured = measureTable(
-    state.canvas,
-    tableOf(span.map((entry) => entry.event)),
-    region.width,
-  );
-  state.measured.set(span[0].event, measured);
-  return retune(span, measured);
-};
-
-// Write the measured heights back over the estimates. `span` is the table's
-// events in the order they were buffered — its opening, its rows, an optional
-// total, then its end — and the measurement comes out in that same order, so
-// the two line up by position and the end simply runs off the shorter list.
-// Reports what the correction moved the running total by.
-/** @type {(span: any[], measured: Measured) => number} */
-let retune = (span, measured) => {
-  let heights = [measured.head.h, ...measured.laid.map((/** @type {any} */ laid) => laid.row.h)];
-  if (measured.totalRow) heights.push(measured.totalRow.h);
-  let delta = 0;
-  for (let [i, h] of heights.entries()) {
-    delta += h - span[i].h;
-    span[i].h = h;
-  }
-  return delta;
-};
-
-// One buffered entry: the event, the block the replay will draw it from, and
-// what it is worth to the running total. A header keeps its block like
-// anything else — the flush that eventually draws it takes the block from the
-// hold rather than wrapping the text again.
-/** @type {(state: Flow, event: any, block: Block | null, width: number) => any} */
-let entryFor = (state, event, block, width) => {
-  let measured = block || measureFor(state, event, width);
-  return { event, block: measured, h: measured ? measured.h : estimate(state, event) };
-};
-
-// The block a buffered event will be drawn from, measured once at the strip
-// width — already known, which is why this can happen before the region has
-// decided anything. Events that are not blocks contribute an `estimate`.
-/** @type {(state: Flow, event: any, width: number) => Block | null} */
-let measureFor = (state, event, width) =>
-  BLOCKS.has(event.type) ? blockOf(state.canvas, event, width) : null;
-
-// Give every outline mark still waiting a position: where its content begins.
-/** @type {(state: Flow) => void} */
-let anchor = (state) => {
-  for (let i = state.marks.length - 1; i >= 0 && state.marks[i].page < 0; i--) {
-    state.marks[i].page = state.canvas.count - 1;
-    state.marks[i].y = state.canvas.y;
-    // The strip too: two instances in two strips share a y, so a mark that
-    // recorded only the page and the cursor would send both bookmarks to the
-    // same place.
-    state.marks[i].x = originOf(state);
-  }
-};
-
-/** @type {(state: Flow) => Group[]} */
-let pending = (state) => state.open.filter((group) => group.held.length);
-
-// A held run, as blocks. A region measured its headers while buffering them,
-// at this same width, so a replayed run reuses those rather than wrapping the
-// same text a second time (ADR 0027).
-/** @type {(canvas: Canvas, held: any[], avail: number) => Block[]} */
-let blocksOf = (canvas, held, avail) =>
-  held.map((entry) => entry.block || blockOf(canvas, entry.event, avail));
-
-/** @type {(state: Flow, extra: number, runs: Block[][]) => number} */
-let needed = (state, extra, runs) =>
-  state.gap + runs.flat().reduce((total, block) => total + block.h, 0) + extra;
-
-/** @type {(state: Flow, need: number) => boolean} */
-let tooTall = (state, need) => need > ceilOf(state) - carried(state) - floorOf(state);
-
-// Degenerate: taller than a page — keep nothing, paginate normally, and
-// repeat nothing afterwards. That last part is what bounds the replayed run
-// for good: every other path drew its headers inside the room a page still
-// had, so a run always leaves space for the content it introduces.
-/** @type {(state: Flow, holding: Group[]) => void} */
-let dropHeld = (state, holding) => {
-  let held = holding.flatMap((group) => group.held);
-  for (let group of holding) group.held = [];
-  state.gap = 0;
-  anchor(state);
-  for (let entry of held) item(state, entry.event, entry.block);
-};
-
-/** @type {(state: Flow, need: number) => void} */
-let settle = (state, need) => {
-  if (state.canvas.y - need < floorOf(state)) advance(state);
-  // The half-line gap is dropped at the head of a column, exactly as it is at
-  // the head of a page: three strips of labels start level or they read as a
-  // ragged grid.
-  if (!freshOf(state)) state.canvas.y -= state.gap;
-  state.gap = 0;
-  anchor(state);
-};
-
-// Drawn and handed back one instance at a time. Nothing in here turns a page
-// — the turn above already did — so an instance taking its blocks the moment
-// they are drawn can never have them replayed on top of themselves.
-/** @type {(state: Flow, holding: Group[], runs: Block[][], avail: number) => void} */
-let drawHeld = (state, holding, runs, avail) => {
-  let x = originOf(state);
-  for (let [i, group] of holding.entries()) {
-    for (let block of runs[i]) drawBlock(state.canvas, block, x, avail);
-    group.blocks.push(...runs[i]);
-    group.held = [];
-  }
-};
-
-/** @type {(state: Flow, extra: number) => void} */
-let flush = (state, extra) => {
-  let runsFor = pending(state);
-  if (!holding(state)) return;
-  let canvas = state.canvas;
-  let avail = widthOf(state);
-  // Measured per instance, so each one takes back exactly the blocks its own
-  // headers were drawn from: no flat list to slice, no order to keep in step.
-  let runs = runsFor.map((group) => blocksOf(canvas, group.held, avail));
-  let need = needed(state, extra, runs);
-  // Against what a fresh column has left once the page has replayed what it
-  // carries. Inside a region that is a strip, and the replay sits above it.
-  if (tooTall(state, need)) return dropHeld(state, runsFor);
-  settle(state, need);
-  drawHeld(state, runsFor, runs, avail);
-};
-
-// Enough of an item that its group header is never left introducing nothing.
-let KEEP_LINES = 2;
-/** @type {(block: Block) => number} */
-let keepWith = (block) =>
-  block.picture ? block.h : Math.min(block.h, heightOf(block.lines.slice(0, KEEP_LINES)));
-
-// Flush any pending header with this item's opening, then place the item. The
-// block is measured once here and handed on rather than wrapped twice.
-/** @type {(state: Flow, event: any, measured?: Block | null) => void} */
-let placeItem = (state, event, measured = null) => {
-  let block = measured || keepBlock(state, event, widthOf(state));
-  if (block && holding(state)) flush(state, keepWith(block));
-  item(state, event, block);
-};
-
-// The block a held header run must keep company with: null when nothing is
-// waiting on it, or when this event is a header itself rather than the content
-// one introduces. The width is the caller's, because a region measures against
-// the strip its content is about to land in rather than the page.
-/** @type {(state: Flow, event: any, width: number) => Block | null} */
-let keepBlock = (state, event, width) =>
-  holding(state) && event.role !== "group-header" ? measureFor(state, event, width) : null;
-
-// Is anything waiting on this item's arrival — a header run, or the gap an
-// instance opens with?
-/** @type {(state: Flow) => boolean} */
-let holding = (state) => state.open.some((group) => group.held.length) || state.gap > 0;
-
-// A half-line gap before each instance (dropped at a page top by `flush`)
-// keeps groups reading as blocks. Every instance becomes an outline entry.
-// `break: "page"` turns the page first — pending ancestor headers stay
-// buffered across it, so they open the fresh page with their content and
-// their own marks anchor there. `reset: "page"` turns the same way, then
-// starts a new `page.number` / `page.total` sequence on the page it opens.
-// A duplicate start on a page that already began a sequence is a zero-length
-// range; `numbered` skips it.
-/** @type {(state: Flow, event: any) => void} */
-let openGroup = (state, event) => {
-  breakFor(state, event);
-  if (event.columns) state.pending = { count: event.columns, owner: event.depth };
-  state.gap = Math.max(state.gap, instanceGap(state.canvas));
-  state.open.push({ held: [], blocks: [] });
-  state.marks.push(markFor(event));
-};
-
-// A real page, inside a region as much as outside one: ADR 0013 declined a
-// `break: "column"`, so this never means the next strip. `turn` restrips.
-/** @type {(state: Flow, event: any) => void} */
-let breakFor = (state, event) => {
-  if (event.break === "page" || event.reset === "page") turn(state);
-  if (event.reset === "page") state.starts.push(state.canvas.count - 1);
-};
-
-/** @type {(event: any) => any} */
-let markFor = (event) => ({
-  // display(), not String(): a Date group key must title its outline bookmark
-  // with the same ISO 8601 UTC text its cells render, on every machine.
-  title: event.name + ": " + display(event.key),
-  titled: false,
-  depth: event.depth,
-  page: -1,
-  y: 0,
-});
-
-// Headers wait for the content they introduce, so one is never stranded at a
-// page bottom. The instance's first header titles its outline entry.
-/** @type {(state: Flow, event: any, title: string | null, block?: Block | null) => void} */
-let holdHeader = (state, event, title, block = null) => {
-  let mark = state.marks[state.marks.length - 1];
-  // A picture has no words to title an outline entry with, so it holds its
-  // place in the run and leaves the title to the next header that has some.
-  if (mark && !mark.titled && title != null) {
-    mark.titled = true;
-    mark.title = title;
-  }
-  state.open[state.open.length - 1].held.push({ event, block });
-};
-
-// A table row's floor height and the gap a group instance opens with: named
-// because the region's estimator reads both, and a constant with two readers
-// and no name drifts between them.
-/** @type {(canvas: Canvas) => number} */
-let rowHeight = (canvas) => LEAD * canvas.base;
-/** @type {(canvas: Canvas) => number} */
-let instanceGap = (canvas) => 0.5 * LEAD * canvas.base;
-
-// What a fresh strip has to hold to take an instance: the span less the
-// opening gap, which `settle` drops at a strip head. This is the one fact the
-// balance model and the placement rule have to agree on, so both read it here
-// rather than each subtracting the gap for itself.
-/** @type {(canvas: Canvas, span: number) => number} */
-let headOf = (canvas, span) => span - instanceGap(canvas);
-
-// --- tables -----------------------------------------------------------------
-
-// Pre-measure one cell: wrapped lines per column width come later; natural
-// width first (no wrapping except hard breaks). `mt`/`mb` go unread: SCHEMA.md
-// gives flow spacing no meaning inside a table row, in either target.
-/** @type {(canvas: Canvas, cell: any, rowStyle: any) => any} */
-let cellOf = (canvas, cell, rowStyle) => {
-  let style = stack(canvas, rowStyle, cell.style);
-  let list = atoms(canvas, cell.tokens, style);
-  let natural = wrap(canvas, list, Infinity).reduce((widest, line) => Math.max(widest, line.w), 0);
-  return {
-    list,
-    natural: natural + 2 * PADX,
-    align: style.align,
-    bg: col(style.background),
-    underline: !!style.underline,
-    strikethrough: !!style.strikethrough,
-  };
-};
-
-/** @type {(canvas: Canvas, cells: any[], widths: number[]) => { cells: any[], h: number }} */
-let rowOf = (canvas, cells, widths) => {
-  let h = rowHeight(canvas);
-  let out = cells.map((cell, i) => {
-    let inner = Math.max(widths[i] - 2 * PADX, 1);
-    let lines = cell.list.length ? dress(wrap(canvas, cell.list, inner), cell) : [];
-    let cellHeight = heightOf(lines) + 2 * PADY;
-    if (cellHeight > h) h = cellHeight;
-    return { ...cell, lines };
-  });
-  return { cells: out, h };
-};
-
-/** @type {(canvas: Canvas, cell: any, bg: string | null, x: number, y: number, w: number, h: number) => void} */
-let fillCell = (canvas, cell, bg, x, y, w, h) => {
-  if (cell.bg && cell.bg !== bg) canvas.rect(cell.bg, x, y, w, h);
-};
-
-/** @type {(canvas: Canvas, cell: any, lines: any[], x: number, y: number, w: number) => void} */
-let writeCell = (canvas, cell, lines, x, y, w) => {
-  for (let line of lines) {
-    canvas.drawLine(line, x + PADX, y, w - 2 * PADX, cell.align);
-    y -= line.h;
-  }
-};
-
-// Paint a band of cells `h` tall and advance past it. `lines[i]` is what
-// column `i` draws here: its whole cell, or one slice of a row too tall to
-// fit — which is why `padTop` is a parameter, a continuation starting flush.
-/**
- * @type {(canvas: Canvas, cells: any[], lines: any[][], h: number, padTop: boolean,
- *   xOffsets: number[], widths: number[], bg: string | null) => void}
- */
-let paintCells = (canvas, cells, lines, h, padTop, xOffsets, widths, bg) => {
-  if (bg) canvas.rect(bg, xOffsets[0], canvas.y - h, sum(widths), h);
-  let y0 = canvas.y - (padTop ? PADY : 0);
-  for (let [i, cell] of cells.entries()) {
-    fillCell(canvas, cell, bg, xOffsets[i], canvas.y - h, widths[i], h);
-    writeCell(canvas, cell, lines[i], xOffsets[i], y0, widths[i]);
-  }
-  canvas.y -= h;
-  canvas.fresh = false;
-};
-
-/**
- * @type {(canvas: Canvas, row: { cells: any[], h: number }, xOffsets: number[],
- *   widths: number[], bg: string | null) => void}
- */
-let drawRow = (canvas, row, xOffsets, widths, bg) =>
-  paintCells(
-    canvas,
-    row.cells,
-    row.cells.map((cell) => cell.lines),
-    row.h,
-    true,
-    xOffsets,
-    widths,
-    bg,
-  );
-
-// The widest of each column's header, rows and total, padding included.
-/** @type {(cols: any[], header: any[], rows: any[], total: any[] | null) => number[]} */
-let naturalWidths = (cols, header, rows, total) =>
-  cols.map((_, i) => {
-    let widest = header[i].natural;
-    for (let row of rows) widest = Math.max(widest, row.cells[i].natural);
-    return total ? Math.max(widest, total[i].natural) : widest;
-  });
-
-/** @type {(values: number[]) => number} */
-let sum = (values) => values.reduce((total, value) => total + value, 0);
-
-// An authored `width` percentage fixes its column; the rest share what is left
-// in proportion to their natural widths. Three cases, one return each — the
-// fall-through is all-authored within budget, honoured exactly.
-//
-// There is no over-commitment case: the engine rejects a document whose fixed
-// shares leave the width-less columns nothing, so `left` is positive whenever
-// an auto column exists and the fixed shares never exceed the content width.
-// That invariant is asserted rather than trusted — falling through with auto
-// columns unplaced would draw them at zero width, an invisible failure — the
-// same fail-loud posture as the measuring canvas's `newPage`.
-/** @type {(cols: any[], natural: number[], avail: number) => number[]} */
-let columnWidths = (cols, natural, avail) => {
-  let fixed = cols.map((column) => Number.isFinite(column.width));
-  if (!fixed.some(Boolean)) {
-    // Natural widths always carry the cell padding, so the sum is never zero.
-    let wanted = sum(natural);
-    return natural.map((width) => (width * avail) / wanted);
-  }
-  let widths = cols.map((col, i) => (fixed[i] ? (col.width / 100) * avail : 0));
-  let auto = natural.map((width, i) => (fixed[i] ? 0 : width));
-  let left = avail - sum(widths);
-  let wanted = sum(auto);
-  // Room for the auto columns: they share what the fixed ones left.
-  if (wanted > 0) {
-    if (left <= 0) throw new Error("over-committed column widths reached the pdf target");
-    return widths.map((width, i) => (fixed[i] ? width : (auto[i] * left) / wanted));
-  }
-  return widths;
-};
-
-// The rule under a table's header row and over its total: the only rule this
-// target draws, always the full content width at the cursor.
-/** @type {(canvas: Canvas, x: number, avail: number) => void} */
-let underline = (canvas, x, avail) => canvas.rule(x, x + avail, canvas.y);
-
-// One table being emitted: what `carryOver`, `sliced` and `put` all need.
-/**
- * @typedef {{ state: Flow, head: { cells: any[], h: number },
- *   xOffsets: number[], widths: number[], x: number, avail: number }} Grid
- */
-
-// Continue in a fresh column: a table that spans columns or pages restates its
-// headings, under whatever headers the open groups replay above them. Both
-// callers reach here on a column something is already drawn in, so the break
-// always breaks.
-//
-// The headings replay at a strip head as well as a page head, unlike a group
-// header (SCHEMA.md): a column of figures under nothing is unreadable, where a
-// group header is merely absent.
-/** @type {(grid: Grid) => void} */
-let carryOver = (grid) => {
-  advance(grid.state);
-  rebase(grid);
-  drawRow(grid.state.canvas, grid.head, grid.xOffsets, grid.widths, null);
-  underline(grid.state.canvas, grid.x, grid.avail);
-};
-
-// Move the grid to the column the cursor is now in. A table's widths are its
-// own for its whole life -- every strip is the same width -- but where its
-// columns start is the strip's, so a break across strips rebases them.
-/** @type {(grid: Grid) => void} */
-let rebase = (grid) => {
-  grid.x = originOf(grid.state);
-  grid.avail = widthOf(grid.state);
-  grid.xOffsets = grid.widths.map((_, i) => grid.x + sum(grid.widths.slice(0, i)));
-};
-
-// The least of a row that can go on a page, so a slice always advances.
-/** @type {(canvas: Canvas, row: { cells: any[] }) => number} */
-let firstSlice = (canvas, row) =>
-  Math.max(
-    rowHeight(canvas),
-    ...row.cells
-      .filter((/** @type {any} */ cell) => cell.lines.length)
-      .map((/** @type {any} */ cell) => PADY + cell.lines[0].h),
-  );
-
-/** @type {(cell: any, next: number[], i: number, used: number, cap: number) => any[]} */
-let takeLines = (cell, next, i, used, cap) => {
-  /** @type {any[]} */
-  let out = [];
-  while (next[i] < cell.lines.length) {
-    let h = cell.lines[next[i]].h;
-    if (out.length && used + h > cap) break;
-    used += h;
-    out.push(cell.lines[next[i]++]);
-  }
-  return out;
-};
-
-/** @type {(row: { cells: any[] }, next: number[]) => boolean} */
-let stillMore = (row, next) =>
-  row.cells.some((/** @type {any} */ cell, /** @type {number} */ i) => next[i] < cell.lines.length);
-
-/** @type {(taken: any[][], pad: number, more: boolean) => number} */
-let sliceH = (taken, pad, more) => {
-  let h = Math.max(0, ...taken.map((lines) => pad + heightOf(lines)));
-  return more ? h : h + PADY;
-};
-
-// A row no page can hold degrades to plain flow: each page takes what fits of
-// each column, always at least one line, with the header replayed between.
-/** @type {(grid: Grid, row: { cells: any[] }, bg: string | null) => void} */
-let sliced = (grid, row, bg) => {
-  let canvas = grid.state.canvas;
-  let next = row.cells.map(() => 0); // first line of each column not yet placed
-  let first = true;
-  for (;;) {
-    let cap = canvas.y - canvas.bottom;
-    let pad = first ? PADY : 0;
-    let taken = row.cells.map((/** @type {any} */ cell, /** @type {number} */ i) =>
-      takeLines(cell, next, i, pad, cap),
-    );
-    let more = stillMore(row, next);
-    // The closing padding belongs to the last slice only.
-    let h = sliceH(taken, pad, more);
-    paintCells(canvas, row.cells, taken, h, first, grid.xOffsets, grid.widths, bg);
-    if (!more) return;
-    carryOver(grid);
-    first = false;
-  }
-};
-
-/** @type {(grid: Grid) => number} */
-let pageCap = (grid) =>
-  ceilOf(grid.state) - carried(grid.state) - floorOf(grid.state) - grid.head.h;
-
-/** @type {(row: { h: number }, keep: number, cap: number) => number} */
-let companion = (row, keep, cap) => (row.h + keep > cap ? 0 : keep);
-
-/** @type {(canvas: Canvas, row: any, cap: number, floor: number) => boolean} */
-let worthBreak = (canvas, row, cap, floor) =>
-  row.h <= cap || canvas.y - floor < Math.min(firstSlice(canvas, row), cap);
-
-/** @type {(state: Flow, row: any, keep: number, cap: number) => boolean} */
-let shouldBreak = (state, row, keep, cap) => {
-  let canvas = state.canvas,
-    floor = floorOf(state);
-  return canvas.y - row.h - keep < floor && worthBreak(canvas, row, cap, floor) && !freshOf(state);
-};
-
-/** @type {(grid: Grid, topRule: boolean, broke: boolean) => void} */
-let openRow = (grid, topRule, broke) => {
-  if (broke) carryOver(grid);
-  if (topRule && !broke) underline(grid.state.canvas, grid.x, grid.avail);
-};
-
-// Place one row, breaking first when that helps. `keep` is a companion row it
-// must not be parted from — the total riding with the last data row.
-// `topRule` is the total's opening rule, which after a break would double the
-// replayed header's.
-/**
- * @type {(grid: Grid, row: { cells: any[], h: number }, bg: string | null,
- *   keep?: number, topRule?: boolean) => void}
- */
-let put = (grid, row, bg, keep = 0, topRule = false) => {
-  let canvas = grid.state.canvas;
-  // The tallest row a fresh column holds, after the replayed group headers and
-  // the replayed column headings. A companion over that can never share a
-  // column, so it stops being a reason to break.
-  let cap = pageCap(grid);
-  keep = companion(row, keep, cap);
-  // A row that will be sliced anyway is only worth breaking for while this
-  // column cannot take even its first slice — beyond that a break buys nothing
-  // and leaves a headings-only column. Clamped to `cap`: a first slice no fresh
-  // column could fit either is no reason to go looking for one.
-  let broke = shouldBreak(grid.state, row, keep, cap);
-  openRow(grid, topRule, broke);
-  if (canvas.y - row.h < canvas.bottom) return sliced(grid, row, bg);
-  drawRow(canvas, row, grid.xOffsets, grid.widths, bg);
-};
-
-/** @type {(canvas: Canvas, row: any) => { cells: any[], bg: any }} */
-let bodyRow = (canvas, row) => ({
-  cells: row.cells.map((/** @type {any} */ cell) => cellOf(canvas, cell, row.style)),
-  bg: col((row.style || {}).background),
-});
-
-/** @type {(canvas: Canvas, buffered: any) => any} */
-let totalCells = (canvas, buffered) =>
-  buffered.total && buffered.total.map((/** @type {any} */ cell) => cellOf(canvas, cell, null));
-
-/** @type {(laid: any[], totalRow: any) => number} */
-let firstH = (laid, totalRow) => (laid.length ? laid[0].row.h : totalRow ? totalRow.h : 0);
-
-/** @type {(totalRow: any, i: number, last: number) => number} */
-let keepTotal = (totalRow, i, last) => (totalRow && i === last ? totalRow.h : 0);
-
-/** @type {(grid: Grid, laid: any[], totalRow: any) => void} */
-let emitRows = (grid, laid, totalRow) => {
-  let last = laid.length - 1;
-  for (let [i, laidRow] of laid.entries())
-    put(grid, laidRow.row, laidRow.bg, keepTotal(totalRow, i, last));
-  if (totalRow) put(grid, totalRow, null, 0, true);
-};
-
-// Lay out a buffered table: measure every cell, allocate the columns, then
-// emit the header, the rows and the total, breaking pages as needed.
-// A buffered table, in the one shape `table` lays out: its columns come from
-// the opening event, its rows are the row events themselves, and its total is
-// the total row's cells. Both readers build it here — the replay, collecting
-// events as they arrive, and the region buffer, reading them back off what it
-// held — so a new table event kind cannot reach one and miss the other.
-/** @type {(events: any[]) => any} */
-let tableOf = (events) => ({
-  columns: events[0].columns,
-  rows: events.filter((event) => event.type === "row"),
-  total: events.find((event) => event.type === "total-row")?.cells ?? null,
-});
-
-/**
- * @typedef {{ widths: number[], head: any, laid: any[], totalRow: any }} Measured
- */
-// Measure a buffered table at a given width: the column widths every cell has
-// a say in, then each row laid out against them. Everything here is
-// arithmetic over the cells, so the region's buffer can ask for it before
-// anything is drawn — which is the only way a row's real height is known
-// early enough to balance on (bead `quario-cgk`).
-/** @type {(canvas: Canvas, buffered: any, avail: number) => Measured} */
-let measureTable = (canvas, buffered, avail) => {
-  let cols = /** @type {any[]} */ (buffered.columns);
-  let header = cols.map((/** @type {any} */ col) => cellOf(canvas, col.header, null));
-  let rows = buffered.rows.map((/** @type {any} */ row) => bodyRow(canvas, row));
-  let total = totalCells(canvas, buffered);
-  let widths = columnWidths(cols, naturalWidths(cols, header, rows, total), avail);
-  return {
-    widths,
-    head: rowOf(canvas, header, widths),
-    laid: rows.map((/** @type {any} */ row) => ({
-      row: rowOf(canvas, row.cells, widths),
-      bg: row.bg,
-    })),
-    totalRow: total && rowOf(canvas, total, widths),
-  };
-};
-
-/** @type {(state: Flow, buffered: any) => void} */
-let table = (state, buffered) => {
-  let canvas = state.canvas;
-  // A table inside a region is measured against the strip, not the page: an
-  // authored `width` percentage is a share of the column it lands in
-  // (SCHEMA.md, "Page columns").
-  let avail = widthOf(state);
-  let x = originOf(state);
-  // Measured already if a region buffered this table: the balance model needed
-  // its real row heights, at this same width, and that is the same
-  // measurement — so the replay draws it without wrapping every cell again.
-  let { widths, head, laid, totalRow } =
-    state.measured.get(buffered.opening) || measureTable(canvas, buffered, avail);
-  let xOffsets = widths.map((_, i) => x + sum(widths.slice(0, i)));
-
-  /** @type {Grid} */
-  let grid = { state, head, xOffsets, widths, x, avail };
-
-  // A pending group header keeps the table's header row and its first row.
-  flush(state, grid.head.h + firstH(laid, totalRow));
-  if (canvas.y - grid.head.h < floorOf(state)) {
-    advance(state);
-    rebase(grid);
-  }
-  drawRow(canvas, grid.head, grid.xOffsets, widths, null);
-  underline(canvas, grid.x, grid.avail);
-  // The last data row keeps the total row with it, so a total is never
-  // stranded alone at a page top.
-  emitRows(grid, laid, totalRow);
-};
-
-// --- page bands -------------------------------------------------------------
-
-// Lay page band items out at a fixed spot (no page breaks): used per page
-// with the real `{ number, total }`, and once as a probe to reserve height.
-/** @type {(canvas: Canvas, items: any[], yTop: number) => number} */
-let band = (canvas, items, yTop) => {
-  let avail = canvas.content;
-  let saved = canvas.y,
-    fresh = canvas.fresh;
-  canvas.y = yTop;
-  canvas.fresh = false;
-  // Folded straight into the draw, the way the body walk folds straight into
-  // `route`: the folder emits in order and nothing here needs the band whole.
-  let fold = splitFolder((event) =>
-    drawBlock(canvas, blockOf(canvas, event, avail), canvas.margin, avail),
-  );
-  for (let event of items) fold(event);
-  let h = yTop - canvas.y;
-  canvas.y = saved;
-  canvas.fresh = fresh;
-  return h;
-};
-
-// Measure a band without drawing it, to reserve its height. The trial render
-// goes onto a measuring canvas of its own, which can draw nothing and holds
-// nothing through which a document could be reached — so it runs while a live
-// canvas is open on one, with no live state for it to disturb.
-/** @type {(geo: Frame, fonts: any, items: any[]) => number} */
-let probe = (geo, fonts, items) => band(measuring(geo, fonts), items, 0);
-
-// The pages every band is probed on, and the whole of what reservation assumes
-// about where a band varies. Two anchors cover each visibility edge — a band
-// hidden on the cover (`visible: '=page.number > 1'`) and a cover-only
-// masthead alike reserve their true height — and the total of two is a
-// stand-in for a count no one knows yet, which SCHEMA.md's cover-page note is
-// about: a band that varies with the real page count, in visibility or in
-// height, is measured as though the document were two pages long.
-let PROBES = [
-  { number: 1, total: 2 },
-  { number: 2, total: 2 },
-];
-
-/**
- * The content box a render's body flows through: the page box less what its
- * page bands need, each band's height plus the gap that separates it from the
- * body. A declared band costs that gap whether or not it measured anything —
- * the gap belongs to the declaration, and a band drawing nothing on either
- * probed page may still draw on page three.
- *
- * Pure, and measured against the page box rather than a live canvas: what a
- * band needs is a property of the page.
- *
- * @type {(geo: Frame, fonts: any, bands: any) => Frame}
- */
-let reserve = (geo, fonts, bands) => {
-  let height = (/** @type {(page: any) => any[]} */ items) =>
-    Math.max(...PROBES.map((page) => probe(geo, fonts, items(page))));
-  return {
-    ...geo,
-    top: geo.top - (bands.header ? height(bands.header) + BAND : 0),
-    bottom: geo.bottom + (bands.footer ? height(bands.footer) + BAND : 0),
-  };
-};
-
-// The page box a canvas presents, before any band narrowed it. `frame` owns how
-// `top`/`bottom` fall out of a page and a margin — "so no caller and no suite
-// has to restate it", as it says next door — and both halves of page furniture
-// want it: reservation to measure against, the draw pass to hang the header
-// from.
-/** @type {(canvas: Canvas) => Frame} */
-let pageBox = (canvas) =>
-  frame(canvas.width, canvas.height, canvas.margin, canvas.base, canvas.style);
-
-// One finished page's furniture, drawn in the strips `reserve` left for it:
-// the header hanging from the top margin, the footer resting on the bottom
-// one, a gap between each and the body either way. The other half of that
-// constant lives directly above, which is the point of the two sitting here
-// together — the pass that draws the bands cannot drift from the reservation
-// that made room for them.
-/** @type {(canvas: Canvas, bands: any, anchor: any) => void} */
-let furniture = (canvas, bands, anchor) => {
-  if (bands.header) band(canvas, bands.header(anchor), pageBox(canvas).top);
-  if (bands.footer) band(canvas, bands.footer(anchor), canvas.bottom - BAND);
-};
-
-// One `{ number, total }` per finished page, from the sequence starts the
-// band flow recorded. A document with no `reset` is one sequence; each
-// resetting instance starts another at the page it opened.
-/** @type {(count: number, starts: number[]) => { number: number, total: number }[]} */
-let numbered = (count, starts) => {
-  let pages = Array(count);
-  let ends = starts.concat(count);
-  for (let s = 0; s < starts.length; s++) {
-    let lo = ends[s];
-    let total = ends[s + 1] - lo;
-    for (let i = lo; i < lo + total; i++) pages[i] = { number: i - lo + 1, total };
-  }
-  return pages;
-};
-
-// --- the band flow ----------------------------------------------------------
-
-/**
- * The band flow (CONTEXT.md): one render's consumer of the banded walk. It owns
- * the placement state — what is held back, what a fresh page owes the groups
- * still open, what is owed before the next instance, what is not yet anchored —
- * and hands out the handlers the walk driver dispatches to, the opening event's
- * among them: the page bands come off the content box there,
- * while the driver still guarantees no second event has been pulled and this
- * band flow's own first page is open and empty.
- *
- * `finish` flushes whatever the last event left pending and returns what the
- * passes over the finished pages still need: the outline marks — the only way
- * to reach them, so an outline read off a band flow that still owes a flush is
- * not a mistake this seam leaves open — the opening event it settled,
- * handed back whole rather than read into, and the per-page `{ number, total }`
- * anchors the furniture pass draws with.
- *
- * @type {(canvas: Canvas) => { handlers: Record<string, (event: any) => void>,
- *   finish: () => { marks: any[], opening: any,
- *     pages: { number: number, total: number }[] } }}
- */
-let flow = (canvas) => {
-  /** @type {Flow} */
-  let state = {
-    canvas,
-    open: [],
-    gap: 0,
-    marks: [],
-    starts: [0],
-    region: null,
-    pending: null,
-    // What a region already measured, keyed by the table's opening event, so
-    // the replay draws that table without wrapping every cell a second time.
-    // Per flow, because the keys are one render's events.
-    measured: new WeakMap(),
-    // Assigned below, once `route` exists: a buffered region replays through
-    // it, and one entry point is what makes the replay take the path the
-    // content would have taken had it never been held.
-    route: () => {},
-  };
-  // The body walk's own folder, emitting each finished event onward to `route`
-  // below. Declared here and bound after `route` exists.
-  /** @type {(event: any) => void} */
-  let fold;
-  // A table is buffered whole before it is laid out: column widths come from
-  // every cell in it, so the last row has to be in hand first.
-  /** @type {any[]} */
-  let collected = [];
-  // The opening event, kept for the caller: this band flow reserves the page
-  // bands off it, and the passes over the finished pages want the rest.
-  /** @type {any} */
-  let opening = null;
-  // The body opens its own first page. Not through `turn`: a canvas that has
-  // drawn nothing is fresh already, and would be left with no page at all.
-  canvas.newPage();
-
-  // What each event does once it is placed for real. A buffered region replays
-  // through this same table, so held content lays out by exactly the path it
-  // would have taken had it never been held.
-  // A block with no title of its own: held back under a group header, placed
-  // anywhere else. Both the image and the split flow this way.
-  /** @type {(event: any, block: Block | null) => void} */
-  let heldOrPlaced = (event, block) =>
-    event.role === "group-header"
-      ? holdHeader(state, event, null, block)
-      : placeItem(state, event, block);
-
-  /** @type {Record<string, (event: any, block: Block | null) => void>} */
-  let placed = {
-    // A header is held rather than placed, and holding is bookkeeping the
-    // replay has to see in its original order — which is why it routes like
-    // everything else instead of reaching the open stack straight away.
-    item: (event, block) =>
-      event.role === "group-header"
-        ? holdHeader(state, event, text(event.tokens), block)
-        : placeItem(state, event, block),
-    // An image flows exactly as an item does, held back in a group header and
-    // placed anywhere else -- the block it becomes carries a height like any
-    // other. It wears no role default: those describe text.
-    image: heldOrPlaced,
-    // A split flows exactly as an image does, for the same reason: one block,
-    // held back in a group header and placed anywhere else. It wears no role
-    // default of its own -- its slots carry theirs.
-    split: heldOrPlaced,
-    "group-start": (event) => openGroup(state, event),
-    "group-end": () => {
-      flush(state, 0);
-      state.open.pop();
-    },
-    // A table is collected as the events it arrived as, and shaped by `tableOf`
-    // once its last one lands — the same constructor the region buffer reads
-    // its own held events back through.
-    "table-start": (event) => void (collected = [event]),
-    row: (event) => void collected.push(event),
-    "total-row": (event) => void collected.push(event),
-    "table-end": () => {
-      table(state, { ...tableOf(collected), opening: collected[0] });
-      collected = [];
-    },
-  };
-  /** @type {(event: any, block: Block | null) => void} */
-  let place = (event, block) => placed[event.type](event, block);
-
-  // Which depth owes or holds the strips, whether or not any content has
-  // opened them yet: an instance that emits nothing still closes with a
-  // full-width footer, and measuring that at a strip width would wrap it to a
-  // column it is not drawn in.
-  let owner = () => (state.region ? state.region.owner : state.pending ? state.pending.owner : -2);
-  /** @type {(event: any) => boolean} */
-  let ownFooter = (event) => event.role === "group-footer" && owner() === state.open.length - 1;
-
-  // Route one event: the declaring node's own bands stay full-width, region
-  // content opens the strips owed to it, and anything arriving while a region
-  // is still deciding is buffered rather than placed.
-  /** @type {(event: any, block?: Block | null) => void} */
-  let route = (event, block = null) => {
-    if (fullBand(event)) fullWidth(event, block);
-    else if (deciding()) buffer(state, event, block);
-    else if (opens(event)) begin(event);
-    else place(event, block);
-  };
-
-  state.route = route;
-  fold = splitFolder(route);
-
-  // Everything drawn across the page rather than down a strip: the declaring
-  // node's own bands, its footer among them.
-  /** @type {(event: any) => boolean} */
-  let fullBand = (event) => ownFooter(event) || isReportBand(event.role);
-
-  // Does this event open the strips a `columns` count owes? A header does not:
-  // it is held, never placed, so the run it belongs to is drawn by the flush
-  // its own content triggers — which is what leaves a columned node's header
-  // above the strips.
-  /** @type {(event: any) => boolean} */
-  let opens = (event) => Boolean(state.pending) && event.role !== "group-header";
-
-  // The instance that owns the strips is the one ending here, so they close
-  // before anything resumes full-width under them. A count the instance never
-  // reached any content for is simply dropped.
-  /** @type {(depth: number) => void} */
-  let endOwned = (depth) => {
-    if (owner() !== depth) return;
-    if (state.region) closeRegion(state);
-    else state.pending = null;
-  };
-
-  // Is the open region still buffering, rather than laying anything out?
-  let deciding = () => Boolean(state.region && state.region.held);
-
-  // The declaring node's own bands, above and below its strips. A count still
-  // owed survives a report header — that band arrives before the body it
-  // columns — but not the owner's own footer, which is the end of what it
-  // would have columned.
-  /** @type {(event: any, block: Block | null) => void} */
-  let fullWidth = (event, block) => {
-    // Asked before the region closes, because that is what it reads.
-    let own = ownFooter(event);
-    closeRegion(state);
-    if (own) state.pending = null;
-    place(event, block);
-  };
-
-  // The first content of a columned node. The node's own header run is drawn
-  // full-width here, before the region exists, which is what keeps it above
-  // the strips; the region then opens at the cursor that left behind. The run
-  // still keeps company with the content it introduces, measured at the strip
-  // width because that is where the content is about to land.
-  /** @type {(event: any) => void} */
-  let begin = (event) => {
-    let owed = /** @type {Pending} */ (state.pending);
-    let block = keepBlock(state, event, stripWidth(state, owed.count));
-    flush(state, block ? keepWith(block) : 0);
-    openRegion(state);
-    buffer(state, event, block);
-  };
-
-  // The report default onto the canvas, before anything is measured. Its
-  // `size` replaces this target's baseline outright, so row heights and band
-  // gaps scale with the document's type rather than staying at a size nothing
-  // is set in; the block itself becomes the outermost layer `stack` composes
-  // (docs/adr/0033). `sizeOf` is what decides a size is usable anywhere in this
-  // target, so it decides it here too -- a computed `size` reaches this
-  // unchecked, and two spellings of that leniency would drift.
-  /** @type {(style: any) => void} */
-  let adoptDefault = (style) => {
-    if (!style) return;
-    canvas.style = style;
-    canvas.base = sizeOf(style, canvas.base);
-  };
-
-  return {
-    handlers: {
-      "report-start": (event) => {
-        opening = event;
-        adoptDefault(event.style);
-        if (event.columns) state.pending = { count: event.columns, owner: -1 };
-        if (!event.page) return;
-        // A frame of its own, never the canvas itself: `measuring` builds
-        // from whatever it is handed, so handing it this canvas would spread
-        // the page passes onto a measurement — and reaching a document is the
-        // one thing a measurement must not be able to do. What a band needs is
-        // a property of the page box in any case, not of a content box
-        // something may already have narrowed.
-        adopt(canvas, reserve(pageBox(canvas), canvas.fonts, event.page));
-      },
-      // Everything else routes: `placed` above says what each event does, and
-      // one entry point is what lets a buffered region replay through it. The
-      // three the folder owns are left out — `split` is not a stream event at
-      // all (the folder mints it) and item and image reach `route` through it.
-      ...Object.fromEntries(
-        Object.keys(placed)
-          .filter((type) => !BLOCKS.has(type))
-          .map((type) => [type, (/** @type {any} */ event) => route(event)]),
-      ),
-      // Item, image and both bracket events all go through the folder, which
-      // routes what is not inside a split straight onward. The item is the one
-      // that wears a band-role default on the way in.
-      "split-start": (event) => fold(event),
-      "split-end": (event) => fold(event),
-      item: (event) => fold(roled(event)),
-      image: (event) => fold(event),
-      "group-end": (event) => {
-        endOwned(event.depth);
-        route(event);
-      },
-    },
-    finish: () => {
-      // A root region reaches here undrained when a report declares `columns`
-      // and no full-width footer followed its body.
-      closeRegion(state);
-      flush(state, 0);
-      return { marks: state.marks, opening, pages: numbered(canvas.count, state.starts) };
-    },
-  };
-};
-
-export { flow, furniture };