@quario/layout 0.2.0 → 0.4.0

package/lib/layout.js

@@ -21,39 +21,64 @@
  * 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 { display, imageError, isReportBand, text } from "quario";
 import { balance } from "./balance.js";
-import { adopt, adoptSettings, frame, measuring } from "./canvas.js";
+/** `Measured` is the measured table's own type, and the flow passes one
+ * through: the region buffer measures early and the replay hands it back.
+ * @import { Measured, TableRow } from './measure.js' */
+
+/** One table being emitted: what `carryOver`, `sliced` and `put` all need. It
+ * holds the flow, so it is the band flow's own — the measured half never sees
+ * a cursor.
+ * @typedef {{ state: Flow, head: TableRow,
+ *   xOffsets: number[], widths: number[], x: number, avail: number }} Grid */
+import { gridOf, measureTable, sum, tableOf } from "./measure.js";
+import { adopt, measuring } from "./canvas.js";
+import { frame } from "./page.js";
 import { intrinsic } from "./image.js";
 import { CELL_PAD, NO_PAD, WHOLE, insetOf, isWhole, paintBox, sliceInset, unbox } from "./box.js";
-import { BAND, col, GUTTER, LEAD, merge, roled, shift, sizeOf, vshift } from "./style.js";
-import { atoms, dress, heightOf, wrap } from "./text.js";
+import {
+  BAND,
+  col,
+  GUTTER,
+  instanceGap,
+  merge,
+  roled,
+  rowHeight,
+  shift,
+  sizeOf,
+  vshift,
+} from "./style.js";
+import { atoms, 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('./canvas.js').Settings} Settings */
+/** @typedef {import('./page.js').Frame} Frame */
+/** @typedef {import('./settings.js').Settings} Settings */
 /** @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).
+// a page turn replays them from. Each entry also carries the `gap` and `skip`
+// that stood before it opened, which is what a hollow instance puts back.
+// `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 {{ pending: any[], blocks: Block[], gap: number, skip: boolean, titled: boolean }} Group
  */
 /**
  * @typedef {{ canvas: Canvas, open: Group[], gap: number, marks: any[],
  *   starts: number[], region: Region | null, pending: Pending | null,
- *   pin: number | null, skipGap: boolean, inHeader: boolean,
- *   route: (event: any, payload?: Block | Measured | null) => void }} Flow
+ *   pin: number | null, skipGap: boolean, inHeader: boolean }} 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.
+ * Where the cursor is and whether a strip is open — the whole of what
+ * page-vs-strip geometry depends on, and less than the whole flow. The five
+ * accessors under "the cursor" below take this, and so do the flow-spacing
+ * helpers beside them, which is how page furniture drives spacing off a canvas
+ * and no region at all.
  * @typedef {{ canvas: Canvas, region: Region | null }} Cursor
  */
 
@@ -87,15 +112,36 @@ import { atoms, dress, heightOf, wrap } from "./text.js";
  * @typedef {{ block: Block, w: number }} SlotPart
  */
 
+// A block no page break may pass through, and the negation of `slice`. The
+// region balancer answers the same question its own way, keyed on the event
+// rather than the block (`UNITS`), so a new kind of one belongs there too.
+/** @type {(block: Block) => boolean} */
+let unsliceable = (block) => Boolean(block.picture || block.parts);
+
 // 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);
+  // Located here rather than in `image.js`, which is handed bytes and a
+  // format and has never heard of a schema: this is the innermost place that
+  // knows both what went wrong and which item asked for it. SCHEMA.md calls
+  // this failure a render error, and a render error names its node.
+  let sized;
+  try {
+    sized = intrinsic(event.bytes, event.format);
+  } catch (cause) {
+    throw imageError(event.path, /** @type {Error} */ (cause).message, cause);
+  }
+  let { w, h } = sized;
   let width = event.fit === "width" ? avail : Math.min(w, avail);
-  return { bytes: event.bytes, format: event.format, w: width, h: (h * width) / w };
+  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
@@ -124,7 +170,7 @@ let blockOf = (canvas, event, avail, under = null) => {
     };
   }
   let size = sizeOf(text, canvas.settings.base);
-  let lines = dress(wrap(atoms(canvas.settings, event.tokens, text), inner, size), text);
+  let lines = wrap(atoms(canvas.settings, event.tokens, text), inner, size);
   return {
     lines,
     bg,
@@ -161,7 +207,15 @@ let drawPicture = (canvas, block, x, avail) => {
   let at = x + shift(block.align, avail - outer);
   paintBox(canvas, at, canvas.y, outer, block.h, block.style, block.bg);
   canvas.box(block.path, at, canvas.y, outer, block.h);
-  canvas.picture(bytes, format, at + inset.l, canvas.y - inset.t - block.drop - h, w, h);
+  canvas.picture(
+    block.path,
+    bytes,
+    format,
+    at + inset.l,
+    canvas.y - inset.t - block.drop - h,
+    w,
+    h,
+  );
   canvas.y -= block.h;
   canvas.fresh = false;
 };
@@ -330,14 +384,24 @@ let drawBlock = (canvas, block, x, avail) =>
  * @typedef {{ count: number, owner: number }} Pending
  */
 
+// --- the cursor -------------------------------------------------------------
+
+// The five below are the whole of how anything reaches page-vs-strip geometry,
+// and they take a `Cursor` — a canvas and the region open on it, if one is —
+// because the region is the only thing that changes any of their answers. The
+// drawing primitives take a bare `Canvas` and read it flat, and that is not an
+// exception to this: a primitive draws where it is told and does not choose a
+// column, so it has nothing to ask. Page furniture reads flat for the same
+// reason — `band` places at the page's own margin and never inside a region.
+// The flow-spacing helpers below take a `Cursor` too: `keepLead` asks
+// `freshOf`, so the spacing and the geometry are one seam, not two.
+
 // 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 `pageFrame` re-derives page furniture from it.
-/** @type {(state: Flow) => number} */
+// region, and the page's content box outside one.
+/** @type {(state: Cursor) => number} */
 let originOf = (state) =>
   state.canvas.margin + (state.region ? state.region.index * (state.region.width + GUTTER) : 0);
-/** @type {(state: Flow) => number} */
+/** @type {(state: Cursor) => 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
@@ -345,7 +409,7 @@ let widthOf = (state) => (state.region ? state.region.width : state.canvas.conte
 // 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} */
+/** @type {(state: Cursor) => number} */
 let floorOf = (state) => {
   let region = state.region;
   if (!region || region.height == null || region.index === region.count - 1)
@@ -353,11 +417,11 @@ let floorOf = (state) => {
   return region.top - region.height;
 };
 // The y a fresh column starts from: a strip's shared top inside a region.
-/** @type {(state: Flow) => number} */
+/** @type {(state: Cursor) => 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`.
+// drawing primitives that move it take a `Canvas` rather than a `Cursor`.
 // `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
@@ -438,7 +502,7 @@ let skipFlow = (state, event, 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
+// The unsliceable 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
@@ -538,12 +602,12 @@ let item = (state, event, measured = null) => {
   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.
+// What a block does when it does not fit where it stands. An unsliceable block
+// 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);
+  unsliceable(block) ? 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
@@ -643,7 +707,7 @@ let stripWidth = (state, count) => (state.canvas.content - GUTTER * (count - 1))
 //
 // 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.
+// page. `held` is that buffer; `null` means the region has decided.
 /** @type {(state: Flow) => void} */
 let openRegion = (state) => {
   let owed = state.pending;
@@ -666,18 +730,14 @@ let openRegion = (state) => {
   };
 };
 
-// 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);
+// Land the region: the cursor drops to whichever strip reached lowest, and
+// full-width content resumes under it on the same page (SCHEMA.md). The last
+// reader of `ends`, which `restrip` empties and `advance` fills — closing is
+// the flow's, because a region still holding has to be laid out first, but
+// where the region lands is geometry and belongs here.
+/** @type {(state: Flow, region: Region) => void} */
+let landRegion = (state, region) => {
+  state.canvas.y = Math.min(state.canvas.y, ...region.ends);
   state.region = null;
 };
 
@@ -739,11 +799,14 @@ let UNITS = {
   },
   row: restated,
   "total-row": restated,
+  // The kinds `unsliceable` names, restated because a strip is costed from the
+  // event rather than the block -- this table's `whole` is the balancer's
+  // model, not the pagination truth. A third such kind belongs in both places.
   image: unbroken,
   split: unbroken,
 };
 
-// An unsplittable block owes a strip nothing but its own height.
+// An entry no strip may cut owes it nothing but its own height.
 /** @type {(entry: any) => Unit} */
 function unbroken(entry) {
   return unsplit(entry.h, entry.h);
@@ -766,20 +829,21 @@ let stripHeight = (state, region, own) =>
     ? null
     : balance(unitsOf(state, own), region.count, roomOf(state, region), rowHeight(state.canvas));
 
-/** @type {(state: Flow) => void} */
-let commit = (state) => {
+// Decide the region: settle the strip height, stop holding, and hand the held
+// entries back in the order they arrived, for `flow`'s `replay` to walk.
+// Not `commit`: the editor's session already spends that word on a gesture
+// ending, and git spends it on a commit.
+//
+// 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.
+/** @type {(state: Flow) => any[]} */
+let decide = (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.payload);
-  }
+  return held;
 };
 
 // A group instance is the atomic unit inside a region: one that would cross a
@@ -864,10 +928,11 @@ let NESTING = { "group-start": 1, "group-end": -1 };
 // 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, payload: Block | Measured | null) => void} */
-let buffer = (state, event, payload) => {
+// kept. Answers whether that event filled it: a buffer that outgrows what the
+// strips could hold has answered the balancing question early, and everything
+// after it streams.
+/** @type {(state: Flow, event: any, payload: Block | Measured | null, hollow: boolean) => boolean} */
+let buffer = (state, event, payload, hollow) => {
   let region = /** @type {Region} */ (state.region);
   // The one door into the held list, so it is where the buffer's own walk is
   // kept. A bracket buffered here is a bracket the open stack will not see
@@ -877,7 +942,33 @@ let buffer = (state, event, payload) => {
   /** @type {any[]} */ (region.held).push(entry);
   region.measured += entry.h;
   if (event.type === "table-end") region.measured += remeasure(state, region, entry);
-  if (outgrown(state, region)) commit(state);
+  if (hollow) region.measured -= refund(/** @type {any[]} */ (region.held));
+  return outgrown(state, region);
+};
+
+// Give back what `WORTH` charged the opening of an instance that turned out
+// hollow, and zero the entry so the replay's `spans` walk agrees. Taken as the
+// close lands rather than at commit because `outgrown` is tested on every
+// buffered event: a region carrying a phantom height can give up on balancing
+// before it ever reaches the commit that would have corrected it.
+//
+// The walk back is over brackets only, which is safe precisely because the
+// caller has already established the instance is hollow — there is nothing
+// else between the two ends to walk over. Nested hollow instances refunded
+// themselves on the way in, so each charge is given back exactly once.
+/** @type {(held: any[]) => number} */
+let refund = (held) => {
+  let depth = 0;
+  for (let i = held.length - 2; i >= 0; i--) {
+    if (held[i].event.type === "group-end") depth++;
+    else if (depth) depth--;
+    else {
+      let charged = held[i].h;
+      held[i].h = 0;
+      return charged;
+    }
+  }
+  return 0;
 };
 
 // A table's events reach the buffer one at a time, and each is worth a bare
@@ -963,7 +1054,7 @@ let anchor = (state) => {
 };
 
 /** @type {(state: Flow) => Group[]} */
-let pending = (state) => state.open.filter((group) => group.held.length);
+let pending = (state) => state.open.filter((group) => group.pending.length);
 
 /** @type {(state: Flow, extra: number, runs: Block[][]) => number} */
 let needed = (state, extra, runs) =>
@@ -974,12 +1065,12 @@ let needed = (state, extra, runs) =>
 // 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 = [];
+let dropPending = (state, holding) => {
+  let waiting = holding.flatMap((group) => group.pending);
+  for (let group of holding) group.pending = [];
   state.gap = 0;
   anchor(state);
-  for (let entry of held) item(state, entry.event, entry.block);
+  for (let entry of waiting) item(state, entry.event, entry.block);
 };
 
 /** @type {(state: Flow, need: number) => void} */
@@ -997,12 +1088,12 @@ let settle = (state, need) => {
 // — 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 drawPending = (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 = [];
+    group.pending = [];
   }
 };
 
@@ -1018,27 +1109,25 @@ let flush = (state, extra) => {
   // at this same width, so a replayed run reuses those rather than wrapping
   // the same text a second time (ADR 0027).
   let runs = runsFor.map((group) =>
-    group.held.map((entry) => entry.block || blockOf(canvas, entry.event, avail)),
+    group.pending.map((entry) => entry.block || blockOf(canvas, entry.event, 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 (need > ceilOf(state) - carried(state) - floorOf(state)) return dropHeld(state, runsFor);
+  if (need > ceilOf(state) - carried(state) - floorOf(state)) return dropPending(state, runsFor);
   settle(state, need);
-  drawHeld(state, runsFor, runs, avail);
+  drawPending(state, runsFor, runs, avail);
 };
 
 // Enough of an item that its group header is never left introducing nothing.
-// The unsplittable blocks are kept whole -- the same `picture || parts` pair
-// `overflow` moves rather than slices. There is no first part of one to keep
-// company with: a split's own `lines` are empty, so clipping to `KEEP_LINES`
-// would reserve nothing at all and strand the run it was called to protect.
+// An unsliceable block is kept whole -- the same blocks `overflow` moves
+// rather than slices. There is no first part of one to keep company with: a
+// split's own `lines` are empty, so clipping to `KEEP_LINES` would reserve
+// nothing at all and strand the run it was called to protect.
 let KEEP_LINES = 2;
 /** @type {(block: Block) => number} */
 let keepWith = (block) =>
-  block.picture || block.parts
-    ? block.h
-    : Math.min(block.h, heightOf(block.lines.slice(0, KEEP_LINES)));
+  unsliceable(block) ? 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.
@@ -1060,7 +1149,7 @@ let keepBlock = (state, event, width) =>
 // 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;
+let holding = (state) => state.open.some((group) => group.pending.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.
@@ -1070,16 +1159,52 @@ let holding = (state) => state.open.some((group) => group.held.length) || state.
 // 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.
+// Run `seen` on every event before the handler that acts on it. The stream is
+// the only place hollowness can be read in order: past this point a region may
+// hold an event back for a commit that lands after its own instance has closed.
+/** @type {(seen: (event: any) => void, handlers: Record<string, (event: any) => void>) => Record<string, (event: any) => void>} */
+let tracked = (seen, handlers) =>
+  Object.fromEntries(
+    Object.entries(handlers).map(([type, handle]) => [
+      type,
+      (/** @type {any} */ event) => {
+        seen(event);
+        handle(event);
+      },
+    ]),
+  );
+
 /** @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 = state.skipGap ? 0 : Math.max(state.gap, instanceGap(state.canvas));
+  let gap = state.gap;
+  let skip = state.skipGap;
+  state.gap = skip ? 0 : Math.max(state.gap, instanceGap(state.canvas));
   state.skipGap = false;
-  state.open.push({ held: [], blocks: [] });
+  state.open.push({ pending: [], blocks: [], gap, skip, titled: false });
   state.marks.push(markFor(event));
 };
 
+// Put back everything opening this instance displaced, so a hollow one leaves
+// the flow exactly as it found it. Restoring rather than zeroing is the whole
+// point: `Math.max` folded any ancestor's gap into this one, and a close that
+// zeroed would rob the parent of a gap its own opening earned. The pinned
+// header's `skip` travels the same way — a hollow instance is not the band the
+// pin was suppressing the gap for, so the suppression passes through it to
+// whatever lands next. The mark goes too: the outline is what a reader opens,
+// and a bookmark onto content this instance did not draw is a worse answer
+// than no bookmark. It is this instance's mark for certain — a non-hollow
+// child would have made this instance non-hollow, and a hollow one already
+// took its own back.
+/** @type {(state: Flow) => void} */
+let unopen = (state) => {
+  let frame = state.open[state.open.length - 1];
+  state.gap = frame.gap;
+  state.skipGap = frame.skip;
+  state.marks.pop();
+};
+
 // 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} */
@@ -1093,7 +1218,6 @@ 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,
@@ -1103,24 +1227,24 @@ let markFor = (event) => ({
 // 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 group = state.open[state.open.length - 1];
   let mark = state.marks[state.marks.length - 1];
+  // Whether a header has claimed this entry is the open instance's own fact,
+  // not the outline entry's: a Mark is what a consumer receives, and it
+  // carries only what `index.d.ts` declares. The two records correspond here
+  // because `openGroup` pushes them together and this only ever runs inside
+  // that instance's own header band, before any nested group opens -- groups
+  // pop from `open` while their marks stay, so nowhere else may assume it.
+  //
   // 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;
+  if (mark && !group.titled && title != null) {
+    group.titled = true;
     mark.title = title;
   }
-  state.open[state.open.length - 1].held.push({ event, block });
+  group.pending.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.settings.base;
-/** @type {(canvas: Canvas) => number} */
-let instanceGap = (canvas) => 0.5 * LEAD * canvas.settings.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
@@ -1130,60 +1254,6 @@ 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) => {
-  // A row's block reaches its cells with no box in it: the engine resolved
-  // that half onto the cells themselves before the event was emitted
-  // (SCHEMA.md, "Style declarations"), which is why the inset and the ink
-  // both read the cell and a row is never asked for a box it cannot have.
-  let style = merge(rowStyle, unbox(cell.style));
-  let inset = insetOf(cell.style, CELL_PAD);
-  let list = atoms(canvas.settings, cell.tokens, style);
-  let natural = wrap(list, Infinity, sizeOf(style, canvas.settings.base)).reduce(
-    (widest, line) => Math.max(widest, line.w),
-    0,
-  );
-  return {
-    list,
-    natural: natural + inset.l + inset.r,
-    align: style.align,
-    valign: style.valign,
-    bg: col(style.background),
-    underline: !!style.underline,
-    strikethrough: !!style.strikethrough,
-    inset,
-    style: cell.style,
-    path: cell.path,
-  };
-};
-
-/** @type {(canvas: Canvas, cells: any[], widths: number[]) => { cells: any[], h: number }} */
-let rowOf = (canvas, cells, widths) => {
-  let h = rowHeight(canvas);
-  /** @type {number[]} */
-  let owns = [];
-  let out = cells.map((cell, i) => {
-    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(cell.list, inner, cell.list[0].size), cell)
-      : [];
-    let own = heightOf(lines) + cell.inset.t + cell.inset.b;
-    if (own > h) h = own;
-    owns.push(own);
-    return { ...cell, lines };
-  });
-  // The row's height is known only now, so the slack each cell's `valign`
-  // reads is measured here, as `splitBlock` measures a slot's.
-  for (let [i, cell] of out.entries()) cell.drop = vshift(cell.valign, h - owns[i]);
-  return { cells: out, h };
-};
-
 /** @type {(canvas: Canvas, cell: any, bg: any, 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);
@@ -1243,107 +1313,7 @@ let drawRow = (canvas, row, xOffsets, widths, bg) => {
   );
 };
 
-// The column geometry one row sees. A cell covering several columns starts
-// where the first of them starts and is as wide as all of them together; a row
-// that spans nothing sees the columns themselves, and pays nothing for the
-// feature. `null` spans is that row -- every data row, and every total row
-// whose cells each cover one column.
-/** @type {(cells: any[]) => number[] | null} */
-let spansOf = (cells) =>
-  cells.some((cell) => cell.span > 1) ? cells.map((cell) => cell.span || 1) : null;
-// One value per cell, walking the columns each of them covers. Reached only
-// for a row that spans, so the closure it takes costs nothing per data row.
-/** @type {(spans: number[], pick: (at: number, span: number) => number) => number[]} */
-let overSpans = (spans, pick) => {
-  /** @type {number[]} */
-  let out = [];
-  let at = 0;
-  for (let span of spans) {
-    out.push(pick(at, span));
-    at += span;
-  }
-  return out;
-};
-/** @type {(widths: number[], spans: number[] | null) => number[]} */
-let spanWidths = (widths, spans) =>
-  spans ? overSpans(spans, (at, span) => sum(widths.slice(at, at + span))) : widths;
 /** @type {(xOffsets: number[], spans: number[] | null) => number[]} */
-let spanOffsets = (xOffsets, spans) => (spans ? overSpans(spans, (at) => xOffsets[at]) : xOffsets);
-
-// The widest of each column's header, rows and totals, padding included.
-//
-// A cell covering more than one column has no say in their widths (SCHEMA.md):
-// what a span states is which columns a cell reaches across, never how wide
-// they are. So a column can end up with no voter at all -- every cell above it
-// spans over it -- which only an empty table reaches, since a data row never
-// spans. It opens at the padding floor rather than at nothing, so an empty
-// table still shows the geometry it promises.
-/**
- * @typedef {{ cells: any[], spans: number[] | null }} Voting
- */
-/** @type {(cols: any[], header: Voting, rows: Voting[], totals: Voting[]) => number[]} */
-let naturalWidths = (cols, header, rows, totals) => {
-  /** @type {(number | null)[]} */
-  let widest = cols.map(() => null);
-  /** @type {(at: number, natural: number) => void} */
-  let widen = (at, natural) => {
-    let held = widest[at];
-    if (held === null || natural > held) widest[at] = natural;
-  };
-  /** @type {(row: Voting) => void} */
-  let vote = (row) => {
-    let at = 0;
-    for (let [i, cell] of row.cells.entries()) {
-      let span = row.spans ? row.spans[i] : 1;
-      if (span === 1) widen(at, cell.natural);
-      at += span;
-    }
-  };
-  vote(header);
-  for (let row of rows) vote(row);
-  for (let row of totals) vote(row);
-  return widest.map((width) => (width === null ? CELL_PAD.l + CELL_PAD.r : width));
-};
-
-/** @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 layout");
-    return widths.map((width, i) => (fixed[i] ? width : (auto[i] * left) / wanted));
-  }
-  return widths;
-};
-
-// One table being emitted: what `carryOver`, `sliced` and `put` all need.
-/**
- * @typedef {{ cells: any[], h: number, style?: any, spans?: number[] | null }} TableRow
- * @typedef {{ state: Flow, head: TableRow,
- *   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
@@ -1356,18 +1326,6 @@ let columnWidths = (cols, natural, avail) => {
 /** @type {(row: { style?: any }) => any} */
 let rowFill = (row) => col((row.style || {}).background);
 
-// What this row draws against: the grid's own columns, or the merged geometry
-// a spanning row sees. Read at draw time rather than kept on the row, because
-// `rebase` moves the offsets under it every time the table crosses a strip.
-/** @type {(grid: Grid, row: TableRow) => { xOffsets: number[], widths: number[] }} */
-let gridOf = (grid, row) =>
-  row.spans
-    ? {
-        xOffsets: spanOffsets(grid.xOffsets, row.spans),
-        widths: spanWidths(grid.widths, row.spans),
-      }
-    : grid;
-
 /** @type {(grid: Grid) => void} */
 let carryOver = (grid) => {
   advance(grid.state);
@@ -1509,74 +1467,6 @@ let emitRows = (grid, laid, totalRows) => {
   for (let row of totalRows) put(grid, row, rowFill(row), 0);
 };
 
-// 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) => {
-  let opening = events[0];
-  return {
-    columns: opening.columns.map((/** @type {any} */ col) => ({ ...col })),
-    // A header cell arrives without a path of its own; the column's is what
-    // its box names, so it rides on the cell from here, where both readers
-    // assemble the table. A column a neighbour's span covers declares no
-    // header, so this is the header *row* -- as many cells as the columns
-    // wrote, which is fewer than the columns whenever one spans.
-    header: opening.columns
-      .filter((/** @type {any} */ col) => col.header)
-      .map((/** @type {any} */ col) => ({ ...col.header, path: col.path })),
-    headerStyle: opening.style,
-    rows: events.filter((event) => event.type === "row"),
-    // The events themselves, as `rows` are: a total row is a row, and the
-    // buffer files each corrected height under the event it was measured from.
-    totals: events.filter((event) => event.type === "total-row"),
-  };
-};
-
-/**
- * @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
-// 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);
-  /** @type {(cells: any[], style: any, spans: number[] | null) => Voting & { style: any }} */
-  let measured = (cells, style, spans) => ({
-    cells: cells.map((/** @type {any} */ cell) => cellOf(canvas, cell, style)),
-    spans,
-    style,
-  });
-  let header = measured(buffered.header, buffered.headerStyle, spansOf(buffered.header));
-  // A data row's cells are the columns' own, so nothing in one can span
-  // (SCHEMA.md, "Span"). Asking each row anyway would scan every cell of the
-  // table to rediscover what the schema already guarantees.
-  let rows = buffered.rows.map((/** @type {any} */ row) => measured(row.cells, row.style, null));
-  let totals = buffered.totals.map((/** @type {any} */ row) =>
-    measured(row.cells, row.style, spansOf(row.cells)),
-  );
-  let widths = columnWidths(cols, naturalWidths(cols, header, rows, totals), avail);
-  // Each row wraps against the geometry it sees, which is the columns' own
-  // unless one of its cells spans.
-  /** @type {(row: Voting & { style: any }) => any} */
-  let laidOut = (row) => ({
-    ...rowOf(canvas, row.cells, spanWidths(widths, row.spans)),
-    spans: row.spans,
-    style: row.style,
-  });
-  return {
-    widths,
-    head: laidOut(header),
-    laid: rows.map(laidOut),
-    totalRows: totals.map(laidOut),
-  };
-};
-
 // Lay out one table from the events it arrived as: measure every cell,
 // allocate the columns, then emit the header, the rows and the total,
 // breaking pages as needed.
@@ -1678,14 +1568,15 @@ let reserve = (geo, settings, bands) => {
   };
 };
 
-// The page frame 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. Named apart from `page.js`'s exported `pageBox`, which validates
-// a host's `page` option and is a different thing entirely.
+// The page frame a canvas presents, recovered from the canvas after `adopt`
+// narrowed it. Only `top`/`bottom` were overwritten there; `width`, `height`
+// and `margin` are still the page's own, so this re-derives the two that went
+// through the same `frame` every other consumer reads — a derivation from live
+// fields, never a copy that could drift from one. Both halves of page furniture
+// want it: reservation to measure against, the draw pass to hang the header
+// from.
 /** @type {(canvas: Canvas) => Frame} */
-let pageFrame = (canvas) => frame(canvas.width, canvas.height, canvas.margin);
+let unnarrowed = (canvas) => frame(canvas.width, canvas.height, canvas.margin);
 
 // 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
@@ -1695,7 +1586,7 @@ let pageFrame = (canvas) => frame(canvas.width, canvas.height, canvas.margin);
 // 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), pageFrame(canvas).top);
+  if (bands.header) band(canvas, bands.header(anchor), unnarrowed(canvas).top);
   if (bands.footer) band(canvas, bands.footer(anchor), canvas.bottom - BAND);
 };
 
@@ -1728,12 +1619,12 @@ let numbered = (count, starts) => {
  * `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.
+ * not a mistake this seam leaves open — and the per-page `{ number, total }`
+ * anchors the furniture pass draws with. The opening event itself the entry
+ * peeked for both halves it is built from, so this seam keeps none of it.
  *
  * @type {(canvas: Canvas) => { handlers: Record<string, (event: any) => void>,
- *   finish: () => { marks: any[], opening: any,
+ *   finish: () => { marks: any[],
  *     pages: { number: number, total: number }[] } }}
  */
 let flow = (canvas) => {
@@ -1749,23 +1640,35 @@ let flow = (canvas) => {
     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[]} */
   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;
+  // Hollowness is a property of the stream, not of what gets drawn: an
+  // instance is hollow when nothing but hollow brackets arrived between its
+  // own ends. Tracked at the handler layer, which every event reaches exactly
+  // once — `route` is re-entered by a region's replay, and a buffered instance
+  // has to be judged before it is buffered, not after. `filling` is one flag
+  // per open bracket; the verdict rides the closing event itself, so the
+  // buffer and the replay both read the answer the stream gave.
+  /** @type {boolean[]} */
+  let filling = [];
+  /** @type {WeakSet<any>} */
+  let hollows = new WeakSet();
+  // Whatever instance is open drew something. Called for an ordinary event and
+  // for a child that turned out not to be hollow, because those are the same
+  // claim: an instance draws through its content and through its children.
+  let fill = () => {
+    if (filling.length) filling[filling.length - 1] = true;
+  };
+  /** @type {(event: any) => void} */
+  let track = (event) => {
+    if (event.type === "group-start") filling.push(false);
+    else if (event.type !== "group-end") fill();
+    else if (filling.pop()) fill();
+    else hollows.add(event);
+  };
   // 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();
@@ -1803,8 +1706,9 @@ let flow = (canvas) => {
     // default of its own -- its slots carry theirs.
     split: heldOrPlaced,
     "group-start": (event) => openGroup(state, event),
-    "group-end": () => {
-      flush(state, 0);
+    "group-end": (event) => {
+      if (hollows.has(event)) unopen(state);
+      else flush(state, 0);
       state.open.pop();
     },
     // A table is collected as the events it arrived as, and shaped by `tableOf`
@@ -1831,7 +1735,7 @@ let flow = (canvas) => {
   // The nesting the router is at. While the buffer holds, routing runs ahead of
   // placement: nothing has been placed, so `state.open` is frozen at the depth
   // the region opened at and only the buffer knows where the walk really is.
-  // Once `commit` nulls `held`, the replay *is* the placement timeline and the
+  // Once `decide` nulls `held`, the replay *is* the placement timeline and the
   // open stack is exact again.
   let nesting = () =>
     state.region && state.region.held ? state.region.nesting : state.open.length - 1;
@@ -1864,13 +1768,53 @@ let flow = (canvas) => {
   let route = (event, payload = null) => {
     snapPin(event);
     if (fullBand(event)) fullWidth(event, payload);
-    else if (deciding()) buffer(state, event, payload);
+    else if (deciding()) hold(event, payload);
     else if (opens(event)) begin(event);
     else place(event, payload);
   };
 
-  state.route = route;
-  fold = splitFolder(route);
+  // The body walk's own folder, emitting each finished event onward to `route`.
+  let fold = splitFolder(route);
+
+  // Hold one event back in the region's buffer, and lay that buffer out if this
+  // is the event that filled it. Not `holdHeader`: that holds a group's header
+  // for the content it introduces, this holds anything at all for a region
+  // still deciding.
+  /** @type {(event: any, payload: Block | Measured | null) => void} */
+  let hold = (event, payload) => {
+    if (buffer(state, event, payload, hollows.has(event))) replay();
+  };
+
+  // Lay the buffer out: `decide` settles the strip height and hands the held
+  // entries back in order, and this walks them through `route`. The walk lives
+  // here rather than under the region section marker for the reason everything
+  // there is module-level — that section is reachable without the router, and
+  // a walk through `route` is not.
+  let replay = () => {
+    let region = /** @type {Region} */ (state.region);
+    for (let entry of decide(state)) {
+      if (breaksFor(state, region, entry.span)) advance(state);
+      route(entry.event, entry.payload);
+    }
+  };
+
+  // Close the region: anything still held is laid out first, and the region
+  // then lands where `landRegion` puts it.
+  //
+  // Nothing the replay routes can arrive back here, which is why the local
+  // `region` survives the call. `route` asks `fullBand` before `deciding()`, so
+  // a full band is never buffered; and a replayed event, asked `fullBand` a
+  // second time, answers as it did the first, because `nesting()`'s two
+  // branches walk the same brackets — `buffer` carries `region.nesting` through
+  // them while nothing is placed, `state.open` through them once the replay is
+  // placing. The other closer, `endOwned`, is wired above `route` at the
+  // handler layer, where a replay does not reach.
+  let closeRegion = () => {
+    let region = state.region;
+    if (!region) return;
+    if (deciding()) replay();
+    landRegion(state, region);
+  };
 
   // Everything drawn across the page rather than down a strip: the declaring
   // node's own bands, its footer among them.
@@ -1890,7 +1834,7 @@ let flow = (canvas) => {
   /** @type {(depth: number) => void} */
   let endOwned = (depth) => {
     if (owner() !== depth) return;
-    if (state.region) closeRegion(state);
+    if (state.region) closeRegion();
     else state.pending = null;
   };
 
@@ -1905,7 +1849,7 @@ let flow = (canvas) => {
   let fullWidth = (event, payload) => {
     // Asked before the region closes, because that is what it reads.
     let own = ownFooter(event);
-    closeRegion(state);
+    closeRegion();
     if (own) state.pending = null;
     place(event, payload);
   };
@@ -1921,7 +1865,7 @@ let flow = (canvas) => {
     let block = keepBlock(state, event, stripWidth(state, owed.count));
     flush(state, block ? keepWith(block) : 0);
     openRegion(state);
-    buffer(state, event, block);
+    hold(event, block);
   };
 
   /** @type {(event: any) => void} */
@@ -1935,12 +1879,17 @@ let flow = (canvas) => {
   };
 
   return {
-    handlers: {
+    // Every handler is wrapped so `track` sees the stream once, in order, ahead
+    // of the dispatch that may buffer the event for later. One wrap rather than
+    // a call in each handler: a new event type must count towards the instance
+    // it arrives in without anyone remembering to say so.
+    handlers: tracked(track, {
       "report-start": (event) => {
-        opening = event;
-        // Every document-wide fact this target reads, settled in one place and
-        // once: `canvas.js` owns what they are and what taking them means.
-        adoptSettings(canvas.settings, event);
+        // The document-wide settings were built complete from this same event
+        // before the walk began (index.js peeks it), so this handler reads them
+        // through `canvas.settings` and settles nothing — only the page bands,
+        // whose height is not known until here, are taken off it below. The
+        // entry peeked the event too, so nothing is kept for it here.
         if (event.columns) state.pending = { count: event.columns, owner: -1 };
         if (!event.page) {
           pinHeader(event);
@@ -1952,7 +1901,7 @@ let flow = (canvas) => {
         // 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(pageFrame(canvas), canvas.settings, event.page));
+        adopt(canvas, reserve(unnarrowed(canvas), canvas.settings, event.page));
         pinHeader(event);
       },
       // Everything else routes: `placed` above says what each event does, and
@@ -1975,14 +1924,17 @@ let flow = (canvas) => {
         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);
+      closeRegion();
       flush(state, 0);
-      return { marks: state.marks, opening, pages: numbered(canvas.count, state.starts) };
+      return {
+        marks: state.marks,
+        pages: numbered(canvas.count, state.starts),
+      };
     },
   };
 };