@quario/pdf 0.1.0 → 0.3.0

package/lib/layout.js

@@ -21,11 +21,13 @@
  * document's bands claim before anything is placed, and where they are drawn
  * on each finished page once the count is known.
  */
-import { isReportBand, text } from "quario";
+import { display, isReportBand, text } from "quario";
 import { balance } from "./balance.js";
 import { adopt, frame, measuring } from "./canvas.js";
+import { familyName } from "./fonts.js";
 import { intrinsic } from "./image.js";
-import { BAND, GUTTER, LEAD, PADX, PADY, col, merge, roled, shift } from "./style.js";
+import { CELL_PAD, NO_PAD, insetOf, paintBox, unbox } from "./box.js";
+import { BAND, GUTTER, LEAD, col, merge, roled, shift, sizeOf } from "./style.js";
 import { atoms, dress, heightOf, wrap } from "./text.js";
 
 /** @typedef {import('./balance.js').Unit} Unit */
@@ -46,8 +48,15 @@ import { atoms, dress, heightOf, wrap } from "./text.js";
  * @typedef {{ canvas: Canvas, open: Group[], gap: number, marks: any[],
  *   starts: number[], region: Region | null, pending: Pending | null,
  *   measured: WeakMap<any, Measured>,
+ *   pin: number | null, skipGap: boolean, inHeader: boolean,
  *   route: (event: any, block?: Block | null) => void }} Flow
  */
+/**
+ * What flow spacing reads of the page: the cursor and whether a strip is open.
+ * Page furniture has a canvas and no region, so the skip helpers take this
+ * rather than the whole flow.
+ * @typedef {{ canvas: Canvas, region: Region | null }} Cursor
+ */
 
 // 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
@@ -57,31 +66,62 @@ import { atoms, dress, heightOf, wrap } from "./text.js";
  * @typedef {{ bytes: Uint8Array, format: string, w: number, h: number }} Picture
  */
 /**
- * @typedef {{ lines: Line[], picture?: Picture, bg: string | null, align: any,
- *   h: number }} Block
+ * `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, style?: any,
+ *   inset: { t: number, r: number, b: number, l: 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 {(canvas: Canvas, event: any, avail: number) => Picture} */
-let pictureOf = (canvas, event, avail) => {
+/** @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 };
 };
 
-/** @type {(canvas: Canvas, event: any, avail: number) => Block} */
-let blockOf = (canvas, event, avail) => {
-  let style = merge(null, event.style);
-  let bg = col(style.background);
+// `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 text = merge(unbox(under), unbox(event.style));
+  let box = event.style;
+  let bg = col((box || {}).background);
+  let inset = insetOf(box, NO_PAD);
+  let inner = Math.max(avail - inset.l - inset.r, 1);
+  if (event.type === "split") return splitBlock(canvas, event, inner, text, bg, box, inset);
   if (event.type === "image") {
-    let picture = pictureOf(canvas, event, avail);
-    return { lines: [], picture, bg, align: style.align, h: picture.h };
+    let picture = pictureOf(event, inner);
+    return {
+      lines: [],
+      picture,
+      bg,
+      align: text.align,
+      h: picture.h + inset.t + inset.b,
+      style: box,
+      inset,
+    };
   }
-  let lines = dress(wrap(canvas, atoms(canvas, event.tokens, style), Math.max(avail, 1)), style);
-  return { lines, bg, align: style.align, h: heightOf(lines) };
+  let size = sizeOf(text, canvas.base);
+  let lines = dress(wrap(canvas, atoms(canvas, event.tokens, text), inner, size), text);
+  return {
+    lines,
+    bg,
+    align: text.align,
+    h: heightOf(lines) + inset.t + inset.b,
+    style: box,
+    inset,
+  };
 };
 
 // Scale a picture block down to the room it has. Best-effort, and only ever
@@ -89,9 +129,10 @@ let blockOf = (canvas, event, avail) => {
 /** @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;
+  let inner = Math.max(room - block.inset.t - block.inset.b, 1);
+  picture.w *= inner / picture.h;
+  picture.h = inner;
+  block.h = inner + block.inset.t + block.inset.b;
 };
 
 // Draw one block whole at the cursor. A picture's background fills the
@@ -100,27 +141,123 @@ let shrink = (block, room) => {
 // 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 inset = block.inset;
   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;
+  let outer = w + inset.l + inset.r;
+  let at = x + shift(block.align, avail - outer);
+  paintBox(canvas, at, canvas.y, outer, block.h, block.style, block.bg);
+  canvas.picture(bytes, format, at + inset.l, canvas.y - inset.t - h, w, h);
+  canvas.y -= block.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);
+  let inset = block.inset;
+  paintBox(canvas, x, canvas.y, avail, block.h, block.style, block.bg);
+  let y = canvas.y - inset.t;
+  let inner = Math.max(avail - inset.l - inset.r, 1);
   for (let line of block.lines) {
-    canvas.drawLine(line, x, canvas.y, avail, block.align);
-    canvas.y -= line.h;
+    canvas.drawLine(line, x + inset.l, y, inner, block.align);
+    y -= line.h;
   }
+  canvas.y -= block.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, inner: number, text: any,
+ *   bg: string | null, box: any, inset: { t: number, r: number, b: number, l: number }) => Block}
+ */
+let splitBlock = (canvas, event, inner, text, bg, box, inset) => {
+  let widths = slotWidths(event.slots, inner);
+  /** @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), text);
+    if (block.h > h) h = block.h;
+    parts.push({ block, w: widths[i] });
+  }
+  return { lines: [], parts, bg, h: h + inset.t + inset.b, style: box, inset };
+};
+
+/** @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) => {
+  let inset = block.inset;
+  let yTop = canvas.y;
+  paintBox(canvas, x, yTop, avail, block.h, block.style, block.bg);
+  let top = yTop - inset.t;
+  let at = x + inset.l;
+  for (let part of block.parts || []) {
+    canvas.y = top;
+    drawBlock(canvas, part.block, at, part.w);
+    at += part.w;
+  }
+  canvas.y = yTop - block.h;
   canvas.fresh = false;
 };
 
 /** @type {(canvas: Canvas, block: Block, x: number, avail: number) => void} */
 let drawBlock = (canvas, block, x, avail) =>
-  (block.picture ? drawPicture : drawLines)(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
@@ -169,7 +306,7 @@ let ceilOf = (state) => (state.region ? state.region.top : state.canvas.top);
 // 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} */
+/** @type {(state: Cursor) => 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} */
@@ -229,17 +366,42 @@ let fitLines = (canvas, block, i, floor, fresh) => {
 /** @type {(canvas: Canvas, block: Block, floor: number) => boolean} */
 let whole = (canvas, block, floor) => canvas.y - block.h >= floor;
 
-// An image is never split: it moves whole to a fresh column. One that no
-// column can hold is scaled down to the one it lands on -- obeying the
-// guarantee literally would mean dropping it (SCHEMA.md, best-effort). It is
-// the unsplittable block, so a balanced floor never cuts it: only the page's
-// own floor can shrink it.
+/** @type {(style: any, name: string) => number} */
+let spaceOf = (style, name) => {
+  let n = style?.[name];
+  return Number.isFinite(n) && n > 0 ? n : 0;
+};
+
+/** @type {(event: any) => boolean} */
+let pageBand = (event) => event.role === "page-header" || event.role === "page-footer";
+/** @type {(state: Cursor, event: any) => boolean} */
+let keepLead = (state, event) => pageBand(event) || !freshOf(state);
+/** @type {(state: Cursor, event: any) => number} */
+let leadOf = (state, event) => (keepLead(state, event) ? spaceOf(event.style, "spaceBefore") : 0);
+/** @type {(state: Cursor, event: any, name: string) => void} */
+let skipFlow = (state, event, name) => {
+  state.canvas.y -= name === "spaceBefore" ? leadOf(state, event) : spaceOf(event.style, name);
+};
+/** @type {(state: Cursor, event: any) => number} */
+let flowPad = (state, event) => leadOf(state, event) + spaceOf(event.style, "spaceAfter");
+
+// 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 placePicture = (state, block) => {
+let placeWhole = (state, block) => {
   advance(state);
   let canvas = state.canvas;
   let room = canvas.y - canvas.bottom;
-  if (block.h > room) shrink(block, room);
+  if (block.picture && block.h > room) shrink(block, room);
   drawBlock(canvas, block, originOf(state), widthOf(state));
 };
 
@@ -285,12 +447,24 @@ 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);
-  if (block.picture) return placePicture(state, block);
-  slice(state, block);
+  let padded = { ...block, h: block.h + flowPad(state, event) };
+  if (whole(canvas, padded, floorOf(state))) {
+    skipFlow(state, event, "spaceBefore");
+    drawBlock(canvas, block, originOf(state), avail);
+    skipFlow(state, event, "spaceAfter");
+    return;
+  }
+  overflow(state, block);
+  skipFlow(state, event, "spaceAfter");
 };
 
+// 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.
@@ -434,8 +608,9 @@ let closeRegion = (state) => {
 // 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
+// row with the whole emitted total block (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.
@@ -481,9 +656,16 @@ let UNITS = {
   },
   row: restated,
   "total-row": restated,
-  image: (entry) => unsplit(entry.h, entry.h),
+  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) {
@@ -580,11 +762,13 @@ 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 {(canvas: Canvas) => number} */
+let rowWorth = (canvas) => rowHeight(canvas) + CELL_PAD.t + CELL_PAD.b;
 /** @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,
+  row: rowWorth,
+  "total-row": rowWorth,
+  "table-start": rowWorth,
   "group-start": (canvas) => instanceGap(canvas),
 };
 
@@ -639,8 +823,8 @@ let remeasure = (state, region) => {
 // 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 heights = [measured.head.h, ...measured.laid.map((/** @type {any} */ laid) => laid.h)];
+  if (measured.totalRows) for (let row of measured.totalRows) heights.push(row.h);
   let delta = 0;
   for (let [i, h] of heights.entries()) {
     delta += h - span[i].h;
@@ -664,7 +848,7 @@ let entryFor = (state, event, block, width) => {
 // decided anything. Events that are not blocks contribute an `estimate`.
 /** @type {(state: Flow, event: any, width: number) => Block | null} */
 let measureFor = (state, event, width) =>
-  event.type === "item" || event.type === "image" ? blockOf(state.canvas, event, width) : null;
+  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} */
@@ -684,7 +868,7 @@ 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 0020).
+// 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));
@@ -761,7 +945,7 @@ let keepWith = (block) =>
 /** @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));
+  if (block && holding(state)) flush(state, keepWith(block) + flowPad(state, event));
   item(state, event, block);
 };
 
@@ -790,7 +974,8 @@ let holding = (state) => state.open.some((group) => group.held.length) || state.
 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.gap = state.skipGap ? 0 : Math.max(state.gap, instanceGap(state.canvas));
+  state.skipGap = false;
   state.open.push({ held: [], blocks: [] });
   state.marks.push(markFor(event));
 };
@@ -805,7 +990,9 @@ let breakFor = (state, event) => {
 
 /** @type {(event: any) => any} */
 let markFor = (event) => ({
-  title: event.name + ": " + String(event.key),
+  // 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,
@@ -848,16 +1035,22 @@ let headOf = (canvas, span) => span - instanceGap(canvas);
 // 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 = merge(rowStyle, cell.style);
+  let style = merge(unbox(rowStyle), unbox(cell.style));
+  let inset = insetOf(cell.style, CELL_PAD);
   let list = atoms(canvas, cell.tokens, style);
-  let natural = wrap(canvas, list, Infinity).reduce((widest, line) => Math.max(widest, line.w), 0);
+  let natural = wrap(canvas, list, Infinity, sizeOf(style, canvas.base)).reduce(
+    (widest, line) => Math.max(widest, line.w),
+    0,
+  );
   return {
     list,
-    natural: natural + 2 * PADX,
+    natural: natural + inset.l + inset.r,
     align: style.align,
     bg: col(style.background),
     underline: !!style.underline,
     strikethrough: !!style.strikethrough,
+    inset,
+    style: cell.style,
   };
 };
 
@@ -865,9 +1058,14 @@ let cellOf = (canvas, cell, rowStyle) => {
 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;
+    let inner = Math.max(widths[i] - cell.inset.l - cell.inset.r, 1);
+    // A glyph or a hard break occupies; spaces alone are an empty cell.
+    let lines = cell.list.some(
+      (/** @type {{ hard: boolean, space: boolean }} */ atom) => atom.hard || !atom.space,
+    )
+      ? dress(wrap(canvas, cell.list, inner, cell.list[0].size), cell)
+      : [];
+    let cellHeight = heightOf(lines) + cell.inset.t + cell.inset.b;
     if (cellHeight > h) h = cellHeight;
     return { ...cell, lines };
   });
@@ -881,8 +1079,9 @@ let fillCell = (canvas, 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) => {
+  let inset = cell.inset;
   for (let line of lines) {
-    canvas.drawLine(line, x + PADX, y, w - 2 * PADX, cell.align);
+    canvas.drawLine(line, x + inset.l, y, w - inset.l - inset.r, cell.align);
     y -= line.h;
   }
 };
@@ -896,9 +1095,10 @@ let writeCell = (canvas, cell, lines, x, y, w) => {
  */
 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);
+    paintBox(canvas, xOffsets[i], canvas.y, widths[i], h, cell.style, null);
+    let y0 = canvas.y - (padTop ? cell.inset.t : 0);
     writeCell(canvas, cell, lines[i], xOffsets[i], y0, widths[i]);
   }
   canvas.y -= h;
@@ -906,10 +1106,11 @@ let paintCells = (canvas, cells, lines, h, padTop, xOffsets, widths, bg) => {
 };
 
 /**
- * @type {(canvas: Canvas, row: { cells: any[], h: number }, xOffsets: number[],
+ * @type {(canvas: Canvas, row: TableRow, xOffsets: number[],
  *   widths: number[], bg: string | null) => void}
  */
-let drawRow = (canvas, row, xOffsets, widths, bg) =>
+let drawRow = (canvas, row, xOffsets, widths, bg) => {
+  let yTop = canvas.y;
   paintCells(
     canvas,
     row.cells,
@@ -920,14 +1121,17 @@ let drawRow = (canvas, row, xOffsets, widths, bg) =>
     widths,
     bg,
   );
+  paintBox(canvas, xOffsets[0], yTop, sum(widths), row.h, row.style, null);
+};
 
-// 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) =>
+// The widest of each column's header, rows and totals, padding included.
+/** @type {(cols: any[], header: any[], rows: any[], totals: { cells: any[] }[]) => number[]} */
+let naturalWidths = (cols, header, rows, totals) =>
   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;
+    for (let row of totals) widest = Math.max(widest, row.cells[i].natural);
+    return widest;
   });
 
 /** @type {(values: number[]) => number} */
@@ -945,7 +1149,7 @@ let sum = (values) => values.reduce((total, value) => total + value, 0);
 // 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((col) => typeof col.width === "number" && Number.isFinite(col.width));
+  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);
@@ -963,14 +1167,10 @@ let columnWidths = (cols, natural, avail) => {
   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 },
+ * @typedef {{ cells: any[], h: number, style?: any }} TableRow
+ * @typedef {{ state: Flow, head: TableRow,
  *   xOffsets: number[], widths: number[], x: number, avail: number }} Grid
  */
 
@@ -982,12 +1182,14 @@ let underline = (canvas, x, avail) => canvas.rule(x, x + avail, canvas.y);
 // 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 {(row: { style?: any }) => any} */
+let rowFill = (row) => col((row.style || {}).background);
+
 /** @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);
+  drawRow(grid.state.canvas, grid.head, grid.xOffsets, grid.widths, rowFill(grid.head));
 };
 
 // Move the grid to the column the cursor is now in. A table's widths are its
@@ -1007,7 +1209,7 @@ let firstSlice = (canvas, row) =>
     rowHeight(canvas),
     ...row.cells
       .filter((/** @type {any} */ cell) => cell.lines.length)
-      .map((/** @type {any} */ cell) => PADY + cell.lines[0].h),
+      .map((/** @type {any} */ cell) => cell.inset.t + cell.lines[0].h),
   );
 
 /** @type {(cell: any, next: number[], i: number, used: number, cap: number) => any[]} */
@@ -1027,10 +1229,17 @@ let takeLines = (cell, next, i, used, cap) => {
 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;
+/** @type {(cell: any, first: boolean, more: boolean) => number} */
+let vPad = (cell, first, more) => (first ? cell.inset.t : 0) + (more ? 0 : cell.inset.b);
+
+/** @type {(taken: any[][], cells: any[], first: boolean, more: boolean) => number} */
+let sliceH = (taken, cells, first, more) => {
+  let h = 0;
+  for (let [i, lines] of taken.entries()) {
+    let cellH = vPad(cells[i], first, more) + heightOf(lines);
+    if (cellH > h) h = cellH;
+  }
+  return h;
 };
 
 // A row no page can hold degrades to plain flow: each page takes what fits of
@@ -1042,13 +1251,11 @@ let sliced = (grid, row, bg) => {
   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),
+      takeLines(cell, next, i, first ? cell.inset.t : 0, cap),
     );
     let more = stillMore(row, next);
-    // The closing padding belongs to the last slice only.
-    let h = sliceH(taken, pad, more);
+    let h = sliceH(taken, row.cells, first, more);
     paintCells(canvas, row.cells, taken, h, first, grid.xOffsets, grid.widths, bg);
     if (!more) return;
     carryOver(grid);
@@ -1074,21 +1281,13 @@ let shouldBreak = (state, row, keep, cap) => {
   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}
+ * @type {(grid: Grid, row: TableRow, bg: string | null,
+ *   keep?: number) => void}
  */
-let put = (grid, row, bg, keep = 0, topRule = false) => {
+let put = (grid, row, bg, keep = 0) => {
   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
@@ -1100,33 +1299,36 @@ let put = (grid, row, bg, keep = 0, topRule = false) => {
   // 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 (broke) carryOver(grid);
   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 }} */
+/** @type {(canvas: Canvas, row: any) => { cells: any[], style: any }} */
 let bodyRow = (canvas, row) => ({
   cells: row.cells.map((/** @type {any} */ cell) => cellOf(canvas, cell, row.style)),
-  bg: col((row.style || {}).background),
+  style: row.style,
 });
 
 /** @type {(canvas: Canvas, buffered: any) => any} */
-let totalCells = (canvas, buffered) =>
-  buffered.total && buffered.total.map((/** @type {any} */ cell) => cellOf(canvas, cell, null));
+let totalRowsOf = (canvas, buffered) =>
+  buffered.totals.map((/** @type {any} */ row) => ({
+    cells: row.cells.map((/** @type {any} */ cell) => cellOf(canvas, cell, row.style)),
+    style: row.style,
+  }));
 
-/** @type {(laid: any[], totalRow: any) => number} */
-let firstH = (laid, totalRow) => (laid.length ? laid[0].row.h : totalRow ? totalRow.h : 0);
+/** @type {(laid: any[], totalRows: any[]) => number} */
+let firstH = (laid, totalRows) => (laid.length ? laid[0].h : totalRows.length ? totalRows[0].h : 0);
 
-/** @type {(totalRow: any, i: number, last: number) => number} */
-let keepTotal = (totalRow, i, last) => (totalRow && i === last ? totalRow.h : 0);
+/** @type {(totalRows: any[]) => number} */
+let totalsH = (totalRows) => totalRows.reduce((h, row) => h + row.h, 0);
 
-/** @type {(grid: Grid, laid: any[], totalRow: any) => void} */
-let emitRows = (grid, laid, totalRow) => {
+/** @type {(grid: Grid, laid: any[], totalRows: any[]) => void} */
+let emitRows = (grid, laid, totalRows) => {
   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);
+  let keep = totalsH(totalRows);
+  for (let [i, row] of laid.entries()) put(grid, row, rowFill(row), i === last ? keep : 0);
+  for (let row of totalRows) put(grid, row, rowFill(row), 0);
 };
 
 // Lay out a buffered table: measure every cell, allocate the columns, then
@@ -1137,14 +1339,19 @@ let emitRows = (grid, laid, totalRow) => {
 // 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,
-});
+let tableOf = (events) => {
+  let opening = events[0];
+  let totals = events.filter((event) => event.type === "total-row");
+  return {
+    columns: opening.columns,
+    headerStyle: opening.style,
+    rows: events.filter((event) => event.type === "row"),
+    totals: totals.map((row) => ({ cells: row.cells, style: row.style })),
+  };
+};
 
 /**
- * @typedef {{ widths: number[], head: any, laid: any[], totalRow: any }} Measured
+ * @typedef {{ widths: number[], head: any, laid: any[], totalRows: 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
@@ -1154,18 +1361,23 @@ let tableOf = (events) => ({
 /** @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 header = cols.map((/** @type {any} */ col) =>
+    cellOf(canvas, col.header, buffered.headerStyle),
+  );
   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);
+  let totals = totalRowsOf(canvas, buffered);
+  let widths = columnWidths(cols, naturalWidths(cols, header, rows, totals), avail);
   return {
     widths,
-    head: rowOf(canvas, header, widths),
+    head: { ...rowOf(canvas, header, widths), style: buffered.headerStyle },
     laid: rows.map((/** @type {any} */ row) => ({
-      row: rowOf(canvas, row.cells, widths),
-      bg: row.bg,
+      ...rowOf(canvas, row.cells, widths),
+      style: row.style,
+    })),
+    totalRows: totals.map((/** @type {any} */ row) => ({
+      ...rowOf(canvas, row.cells, widths),
+      style: row.style,
     })),
-    totalRow: total && rowOf(canvas, total, widths),
   };
 };
 
@@ -1180,7 +1392,7 @@ let table = (state, buffered) => {
   // 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 } =
+  let { widths, head, laid, totalRows } =
     state.measured.get(buffered.opening) || measureTable(canvas, buffered, avail);
   let xOffsets = widths.map((_, i) => x + sum(widths.slice(0, i)));
 
@@ -1188,16 +1400,15 @@ let table = (state, buffered) => {
   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));
+  flush(state, grid.head.h + firstH(laid, totalRows));
   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);
+  drawRow(canvas, grid.head, grid.xOffsets, widths, rowFill(grid.head));
+  // The last data row keeps the whole emitted total block with it, so a
+  // total is never stranded alone at a page top.
+  emitRows(grid, laid, totalRows);
 };
 
 // --- page bands -------------------------------------------------------------
@@ -1211,7 +1422,14 @@ let band = (canvas, items, yTop) => {
     fresh = canvas.fresh;
   canvas.y = yTop;
   canvas.fresh = false;
-  for (let event of items) drawBlock(canvas, blockOf(canvas, event, avail), canvas.margin, avail);
+  // 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) => {
+    skipFlow({ canvas, region: null }, event, "spaceBefore");
+    drawBlock(canvas, blockOf(canvas, event, avail), canvas.margin, avail);
+    skipFlow({ canvas, region: null }, event, "spaceAfter");
+  });
+  for (let event of items) fold(event);
   let h = yTop - canvas.y;
   canvas.y = saved;
   canvas.fresh = fresh;
@@ -1265,7 +1483,12 @@ let reserve = (geo, fonts, bands) => {
 // 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);
+let pageBox = (canvas) =>
+  Object.assign(frame(canvas.width, canvas.height, canvas.margin, canvas.base, canvas.family), {
+    locale: canvas.locale,
+    currency: canvas.currency,
+    timeZone: canvas.timeZone,
+  });
 
 // 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
@@ -1330,11 +1553,18 @@ let flow = (canvas) => {
     // 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(),
+    pin: null,
+    skipGap: false,
+    inHeader: false,
     // 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[]} */
@@ -1350,6 +1580,14 @@ let flow = (canvas) => {
   // 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
@@ -1362,10 +1600,11 @@ let flow = (canvas) => {
     // 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: (event, block) =>
-      event.role === "group-header"
-        ? holdHeader(state, event, null, block)
-        : placeItem(state, event, block),
+    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);
@@ -1393,11 +1632,28 @@ let flow = (canvas) => {
   /** @type {(event: any) => boolean} */
   let ownFooter = (event) => event.role === "group-footer" && owner() === state.open.length - 1;
 
+  /** @type {(event: any) => boolean} */
+  let stillHeader = (event) =>
+    event.role === "report-header" || (event.type === "split-end" && state.inHeader);
+  /** @type {(event: any) => void} */
+  let snapPin = (event) => {
+    if (state.pin == null) return;
+    if (stillHeader(event)) {
+      state.inHeader = true;
+      return;
+    }
+    if (state.canvas.y < state.pin) throw Error("header: content taller than height");
+    state.canvas.y = state.pin;
+    state.pin = null;
+    state.inHeader = false;
+  };
+
   // 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) => {
+    snapPin(event);
     if (fullBand(event)) fullWidth(event, block);
     else if (deciding()) buffer(state, event, block);
     else if (opens(event)) begin(event);
@@ -1405,6 +1661,7 @@ let flow = (canvas) => {
   };
 
   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.
@@ -1458,12 +1715,51 @@ let flow = (canvas) => {
     buffer(state, event, block);
   };
 
+  // The report default onto the canvas, before anything is measured. It is
+  // narrowed to `family` and `size`, and each replaces this target's own
+  // baseline outright: row heights and band gaps scale with the document's
+  // type rather than staying at a size nothing is set in, and text declaring
+  // no family is set in the document's. Lifting the pair here is the whole of
+  // this target's reading of docs/adr/0033 -- the default reaches a node as a
+  // fallback the canvas carries, never as a layer merged into its style, so a
+  // document-wide fact costs no allocation however many cells a report has.
+  //
+  // `sizeOf` and `familyName` are this target's one reading each of what a
+  // declared size and family amount to, so they read the default here too --
+  // both reach this unchecked from a computed style, and two spellings of that
+  // leniency would drift. Each falls back to what the canvas already carries,
+  // so a default declaring one of the pair leaves the other alone, and one
+  // whose value is unusable leaves this target's own baseline standing.
+  /** @type {(style: any) => void} */
+  let adoptDefault = (style) => {
+    if (!style) return;
+    canvas.base = sizeOf(style, canvas.base);
+    canvas.family = familyName(style) || canvas.family;
+  };
+
+  /** @type {(event: any) => void} */
+  let pinHeader = (event) => {
+    if (event.headerHeight == null) return;
+    let pin = canvas.y - event.headerHeight;
+    if (pin < canvas.bottom) throw Error("header: height exceeds the first page's body");
+    state.pin = pin;
+    state.skipGap = true;
+    state.inHeader = true;
+  };
+
   return {
     handlers: {
       "report-start": (event) => {
         opening = event;
+        canvas.locale = event.locale;
+        canvas.currency = event.currency;
+        canvas.timeZone = event.timeZone;
+        adoptDefault(event.style);
         if (event.columns) state.pending = { count: event.columns, owner: -1 };
-        if (!event.page) return;
+        if (!event.page) {
+          pinHeader(event);
+          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
@@ -1471,22 +1767,31 @@ let flow = (canvas) => {
         // 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));
+        pinHeader(event);
       },
       // Everything else routes: `placed` above says what each event does, and
-      // one entry point is what lets a buffered region replay through it.
-      // Only the roled item needs a word of its own on the way in.
+      // 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).map((type) => [
-          type,
-          type === "item" ? (event) => route(roled(event)) : (event) => route(event),
-        ]),
+        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: () => {
+      snapPin({ type: "report-end" });
       // A root region reaches here undrained when a report declares `columns`
       // and no full-width footer followed its body.
       closeRegion(state);