@quario/layout 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-07
+
+### Added
+
+- The text join reads a cell's own `currency` code, ahead of the instance's
+  default, so every target built on this package presents a per-cell
+  denomination.
+
+### Changed
+
+- **A group instance that renders nothing no longer takes up space.** A group
+  whose header and footer items all resolve `visible: false`, with nothing
+  visible under it either, used to open the same half-line gap as any other
+  instance and could push the content after it onto a new page. A run of them
+  spaced whatever followed by a half-line each, so collapsing a level left the
+  rows above it at uneven distances. Such an instance now occupies nothing at
+  all and adds no PDF bookmark, which is what makes a group collapsible while
+  its rows stay in the aggregates. A group that declares `break: "page"` or
+  `reset: "page"` still starts its page either way. Every document with such a
+  group renders slightly shorter than it did.
+
+- **Numbers presented through `format` now show a fixed two fraction digits,
+  matching every other target** — `1,000.00` where `1,000` was rendered,
+  `21.00%` where `21%` was, and a currency's own minor units in place of a
+  universal two. Because this package presents text and then **measures** it,
+  a formatted cell is now up to three characters wider than it was: a line
+  that just fitted can wrap, which can move a page break in a PDF, the viewer,
+  or an editor preview. Nothing else about wrapping changed.
+
+### Fixed
+
+- **An image failure now names the item that asked for the bytes.** A file too
+  short to carry a size failed saying only that the size could not be read,
+  naming no item, so a report with two pictures gave no way to tell which one
+  was bad. The message is now prefixed with the item's `source` path, as every
+  other render error is.
+
+- **An image the browser cannot decode no longer costs the whole page.** A
+  PNG or JPEG whose pixel data is corrupt past the size in its header lays out
+  like any other — the size is all that is read of it — and used to throw out
+  of `paint()` before its first draw op, leaving the page blank: no white
+  fill, none of the other content, and no licence marking. The image is now
+  drawn as nothing and the page is drawn around it, so what a bad image costs
+  is the image.
+
 ## [0.2.0] - 2026-09-05
 
 ### Added

package/lib/canvas.js

@@ -1,6 +1,11 @@
 /**
  * The drawing surface. Every mark the band flow makes goes through here, so
- * nothing above this module knows what a page is made of.
+ * nothing above this module knows how a page is drawn on. What a page *is* —
+ * its box, and the content box a margin leaves — is `page.js`'s `Frame`, which
+ * arrives here already derived: nothing below that module works one out. What
+ * this one owns is what becomes of it after — `blank` spreads it flat onto the
+ * canvas and `adopt` narrows `top`/`bottom` in place, which is why `layout.js`
+ * re-derives the untouched page frame it hangs a header from.
  *
  * Two adapters satisfy one interface. `listing` records marks onto the display
  * list — pages of ops and hit boxes, which the painters consume; `measuring`
@@ -18,72 +23,19 @@
  * it lands: a list coordinate is measured from the page's top-left corner,
  * `y` descending, the way a screen reads. Points throughout.
  */
-import { baseSans, familyName } from "./fonts.js";
-import { BLACK, dressed, shift, sizeOf } from "./style.js";
+import { baseSans } from "./fonts.js";
+import { BLACK, dressed, shift } from "./style.js";
 
+/** @typedef {import('./page.js').Frame} Frame */
 /** @typedef {import('./text.js').Line} Line */
 /** @typedef {import('./style.js').Color} Color */
+// A canvas holds a render's settings and turns nothing into one: what a
+// settings is, and how an opening event becomes it, is settings.js's.
+/** @typedef {import('./settings.js').Settings} Settings */
 // The list's own shapes — `Op`, `Box`, `Page` — are described once, in the
 // hand-written public declarations, and read back here.
 /** @import { Box, Op, Page } from './index.d.ts' */
 
-// The page box and the content box, and nothing whatever else: geometry, all
-// of it derived below from a page and a margin. Fixed for the document — the
-// one exception is `top`/`bottom`, which the page bands narrow once through
-// `adopt` below, while the first page is still untouched. Everything else that
-// holds for a whole render is `Settings`, next door; a frame carrying either
-// half of that was a type with two lifetimes, and the copy that kept a probe
-// reading the same locale as the draw had to be written out by hand.
-/**
- * @typedef {{ width: number, height: number, margin: number,
- *   content: number, top: number, bottom: number }} Frame
- */
-
-// A frame from the page box: how `content`/`top`/`bottom` fall out of a page
-// and a margin is derived here, once, so no caller and no suite has to restate
-// it and drift from what a real render uses.
-/** @type {(width: number, height: number, margin: number) => Frame} */
-let frame = (width, height, margin) => ({
-  width,
-  height,
-  margin,
-  content: width - 2 * margin,
-  top: height - margin,
-  bottom: margin,
-});
-
-// This layout's baseline type size. Not a host option: a document's type size
-// is the document's own, so it is `style.size` on the report and the number
-// here is only what text renders at when nothing declares one. The XLSX target
-// carries the same 10 for the same reason (docs/adr/0014, docs/adr/0033).
-let BASE = 10;
-
-/**
- * Everything that holds for a whole render and is not geometry: the faces to
- * measure against, the report default narrowed to `family` and `size` (landing
- * in `family` and `base` here), and the three intl facts a formatted value
- * resolves in. Settled once, at
- * `report-start`, by `adoptSettings` below, and only read thereafter.
- *
- * A canvas holds one of these by reference, never a copy, which is the whole
- * reason it is an object. A measuring canvas built off the same settings reads
- * exactly what the listing canvas reads, so a page band cannot be reserved
- * against one locale and drawn in another — an agreement that used to rest on
- * a hand-written copy staying in step.
- *
- * `family` is null when the report declares none, and the intl three are
- * absent when the engine settled none.
- *
- * @typedef {{ fonts: import('./fonts.js').Fonts, base: number,
- *   family: string | null, locale?: string, currency?: string,
- *   timeZone?: string }} Settings
- */
-
-// What a render starts from: the loaded faces, and this target's own baseline
-// standing in for a default no report has declared yet.
-/** @type {(fonts: import('./fonts.js').Fonts) => Settings} */
-let settings = (fonts) => ({ fonts, base: BASE, family: null });
-
 // `y` is the cursor on the open page and `fresh` says nothing has been drawn on
 // it yet, which is what makes a break legal. `count` is how many pages exist.
 /**
@@ -93,8 +45,8 @@ let settings = (fonts) => ({ fonts, base: BASE, family: null });
  *   rect: (color: Color, x: number, y: number, w: number, h: number) => void,
  *   stroke: (x1: number, y1: number, x2: number, y2: number, thickness: number,
  *     color: Color, dash: number[] | null) => void,
- *   picture: (bytes: Uint8Array, format: string, x: number, y: number,
- *     w: number, h: number) => void,
+ *   picture: (path: string | undefined, bytes: Uint8Array, format: string,
+ *     x: number, y: number, w: number, h: number) => void,
  *   drawLine: (line: Line, x: number, yTop: number, avail: number,
  *     align: any) => void,
  *   box: (path: string | undefined, x: number, yTop: number, w: number,
@@ -182,9 +134,12 @@ let listing = (box, render) => {
       dash,
     });
 
+  // `path` rides along for the one consumer that needs to name the item back
+  // to the author: a target whose embedder rejects the bytes has nothing else
+  // to say which image it was, the box beside the op being a different record.
   /** @type {Canvas['picture']} */
-  let picture = (bytes, format, x, y, w, h) =>
-    page.ops.push({ kind: "image", bytes, format, x, y: down(y + h), w, h });
+  let picture = (path, bytes, format, x, y, w, h) =>
+    page.ops.push({ kind: "image", path, bytes, format, x, y: down(y + h), w, h });
 
   // `advances` rides only where a painter can use it: a base-14 face's
   // one-per-code-point shaping, which is what lets a screen stand-in be
@@ -314,42 +269,6 @@ let adopt = (canvas, box) => {
   canvas.y = canvas.top;
 };
 
-/**
- * The document-wide facts off `report-start`, taken once, before anything is
- * measured. The report default 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. Settling the pair here is
- * the whole of this target's reading of docs/adr/0033 — the default reaches a
- * node as a fallback the settings carry, 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 settings already carry, 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.
- *
- * Settled once, the statement `adopt` makes about geometry: these hold for a
- * whole render, so a second event setting them would mean two documents in one.
- * The freeze is what enforces it, and the check is what names it.
- *
- * @param {Settings} render The render's settings.
- * @param {any} event The `report-start` event.
- */
-let adoptSettings = (render, event) => {
-  if (Object.isFrozen(render)) throw Error("adoptSettings: the render settings are fixed");
-  let style = event.style || {};
-  render.base = sizeOf(style, render.base);
-  render.family = familyName(style) || render.family;
-  render.locale = event.locale;
-  render.currency = event.currency;
-  render.timeZone = event.timeZone;
-  Object.freeze(render);
-};
-
 // The unlicensed-output marking (LICENSE section 6): one translucent line
 // drawn corner-to-corner across the finished page — over the content, not
 // under it, so no filled table header or background rectangle can cover it.
@@ -388,4 +307,4 @@ let stamp = (canvas, text) => {
   };
 };
 
-export { adopt, adoptSettings, decorateLine, frame, listing, measuring, settings, stamp };
+export { adopt, decorateLine, listing, measuring, stamp };

package/lib/image.js

@@ -53,6 +53,6 @@ export let intrinsic = (bytes, format) => {
   // The engine vouched for the magic numbers, not for the rest of the file:
   // a truncated header reaches here as a zero, and failing loudly beats
   // drawing an image with no size (SCHEMA.md, "Image item").
-  if (!(w > 0 && h > 0)) throw Error("image: could not read the image's size from its bytes");
+  if (!(w > 0 && h > 0)) throw Error("could not read the image's size from its bytes");
   return { w: w * PER_PX, h: h * PER_PX };
 };

package/lib/index.d.ts

@@ -1,6 +1,9 @@
 import type { Target } from "quario";
 
-/** Page geometry, in PostScript points. Host configuration, never schema. */
+/**
+ * Page geometry, in PostScript points. Host configuration, except that a
+ * document may declare `page.margin` in the host's stead — never both.
+ */
 export interface LayoutPage {
   /** Named size or `[width, height]` in points. Default `'A4'`. */
   size?: "A4" | "letter" | [number, number];
@@ -81,9 +84,14 @@ export interface LineOp {
   dash: number[] | null;
 }
 
-/** An image, placed. `bytes` is the array the source expression yielded. */
+/**
+ * An image, placed. `bytes` is the array the source expression yielded, and
+ * `path` names the schema node it came from — the one thing a target whose
+ * embedder rejects those bytes has to report the failure with.
+ */
 export interface ImageOp {
   kind: "image";
+  path: string | undefined;
   bytes: Uint8Array;
   format: "png" | "jpeg";
   x: number;

package/lib/index.js

@@ -21,10 +21,11 @@
  * file adds none. The package publishes `lib/` verbatim.
  */
 import { breathe, walk } from "quario";
-import { listing, settings, stamp } from "./canvas.js";
+import { listing, stamp } from "./canvas.js";
 import { checkFonts, loadFonts } from "./fonts.js";
 import { flow, furniture } from "./layout.js";
 import { geometry } from "./page.js";
+import { settings } from "./settings.js";
 
 export { PX_PER_POINT, hit, paint } from "./paint.js";
 export { pageBox } from "./page.js";
@@ -78,8 +79,13 @@ export function layout(options) {
     let fonts = await loadFonts(custom);
     let gen = stream(data);
     let first = gen.next();
-    let geo = geometry(options?.page, first.done ? null : first.value);
-    let canvas = listing(geo, settings(fonts));
+    // The opening event carries both halves this render is built from: the page
+    // frame and the document-wide settings. Peeked once here — the settings are
+    // complete and immutable by construction, so no later event can settle them
+    // a second time.
+    let opening = first.done ? null : first.value;
+    let geo = geometry(options?.page, opening);
+    let canvas = listing(geo, settings(fonts, opening));
     // The band flow owns the placement state and every handler over it, and
     // opens the first page as it is built; this file only hands it the stream.
     let { handlers, finish } = flow(canvas);
@@ -88,21 +94,21 @@ export function layout(options) {
       yield* gen;
     }
     await walk(events(), handlers);
-    // The flow settled the opening event on its way past — it reserves the
-    // page bands off it — and hands it back with the marks. What is left on it
-    // is what the passes below want: the band closures to render per page, and
-    // the marking's wording to stamp.
-    // Null when nothing settled one, which reads as a document owing neither.
-    let { marks, opening, pages } = finish();
-    opening = opening || {};
+    // The flow reserved the page bands off the opening event on its way past;
+    // the passes below want the rest of it — the band closures to render per
+    // page, and the marking's wording to stamp. It is the same event peeked
+    // above, so this file reads it straight rather than through `finish`.
+    // Empty when nothing was peeked, which reads as a document owing neither.
+    let { marks, pages } = finish();
+    let doc = opening || {};
     // The passes below run over the finished pages, not the stream — no walk
     // at all — so they open each page themselves and breathe on their own
     // rather than through the driver.
-    await furnish(canvas, opening.page, pages);
+    await furnish(canvas, doc.page, pages);
     // The unlicensed marking goes on last, over content and page furniture
     // alike, once per page (LICENSE section 6). Its wording rode in on
     // `report-start`; only the placement is this layout's.
-    await markPages(canvas, opening.marking);
+    await markPages(canvas, doc.marking);
     return /** @type {Layout} */ ({
       width: geo.width,
       height: geo.height,

package/lib/layout.js

@@ -21,9 +21,10 @@
  * 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";
+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";
@@ -31,29 +32,32 @@ import { atoms, dress, heightOf, wrap } from "./text.js";
 
 /** @typedef {import('./balance.js').Unit} Unit */
 /** @typedef {import('./canvas.js').Canvas} Canvas */
-/** @typedef {import('./canvas.js').Frame} Frame */
-/** @typedef {import('./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 {{ held: any[], blocks: Block[], gap: number, skip: 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 +91,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
@@ -161,7 +186,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 +363,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 +388,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 +396,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 +481,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 +581,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
@@ -666,18 +709,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 +778,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 +808,19 @@ let stripHeight = (state, region, own) =>
     ? null
     : balance(unitsOf(state, own), region.count, roomOf(state, region), rowHeight(state.canvas));
 
-/** @type {(state: Flow) => void} */
+// Commit the region: decide the strip height, stop holding, and hand the held
+// entries back in the order they arrived, for `flow`'s `replay` to walk.
+//
+// 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 commit = (state) => {
   let region = /** @type {Region} */ (state.region);
   let held = /** @type {any[]} */ (region.held);
-  // Marking the spans is also what picks out the region's own children, and
-  // the height is decided from those — so it runs before the replay, not with
-  // it.
   region.height = stripHeight(state, region, spans(held));
   region.held = null;
   restrip(region, region.top);
-  for (let entry of held) {
-    if (breaksFor(state, region, entry.span)) advance(state);
-    state.route(entry.event, entry.payload);
-  }
+  return held;
 };
 
 // A group instance is the atomic unit inside a region: one that would cross a
@@ -864,10 +905,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 +919,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
@@ -1029,16 +1097,14 @@ let flush = (state, extra) => {
 };
 
 // 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.
@@ -1070,16 +1136,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({ held: [], blocks: [], gap, skip });
   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} */
@@ -1519,15 +1621,11 @@ 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,
+    // The header row arrives whole (docs/adr/0053), so both readers -- the
+    // replay and the region buffer -- take the same list rather than each
+    // rebuilding it from the columns.
+    header: opening.header.cells,
+    headerStyle: opening.header.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.
@@ -1678,14 +1776,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 +1794,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 +1827,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 +1848,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 +1914,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`
@@ -1864,13 +1976,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: `commit` decides 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 commit(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 +2042,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 +2057,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 +2073,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 +2087,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 +2109,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 +2132,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),
+      };
     },
   };
 };

package/lib/page.js

@@ -3,8 +3,15 @@
  * it is written. Owned here because every consumer of the list — the PDF
  * target, the viewer, the editor — lays out on the same page, and a size that
  * meant one thing on screen and another on paper would be a silent lie.
+ *
+ * The derivation belongs with the validation: `frame` below turns a validated
+ * page and margin into the geometry everything downstream lays out in, so a
+ * page becomes a content box here and `canvas.js` only takes the answer,
+ * rather than the drawing surface defining the page it draws on. Deriving a
+ * frame is not owning its lifetime, and this module claims only the first:
+ * `adopt` (`canvas.js`) narrows `top`/`bottom` once for the page bands, and
+ * `reserve` (`layout.js`) mints the frame it narrows from.
  */
-import { frame } from "./canvas.js";
 
 // The named sizes. `@quario/pdf` used to own this table, and the two element
 // packages restated it; the layout package is where all three now read it.
@@ -80,11 +87,42 @@ export let pageBox = (page, at = "page") => {
   return { width, height, margin: marginOf(page?.margin, width, height, at + ".margin") };
 };
 
+// The page box and the content box, and nothing whatever else: geometry, all
+// of it derived below from a page and a margin. Fixed for the document — the
+// one exception is `top`/`bottom`, which the page bands narrow once through
+// `adopt` (`canvas.js`), while the first page is still untouched. Everything
+// else that holds for a whole render is that module's `Settings`; a frame
+// carrying either half of that was a type with two lifetimes, and the copy that
+// kept a probe reading the same locale as the draw had to be written out by
+// hand.
+/**
+ * @typedef {{ width: number, height: number, margin: number,
+ *   content: number, top: number, bottom: number }} Frame
+ */
+
+// A frame from the page box: how `content`/`top`/`bottom` fall out of a page
+// and a margin is derived here, once, so no caller and no suite has to restate
+// it and drift from what a real render uses. A render reaches a frame through
+// `geometry` below and never through this; the package entry carries neither,
+// so no host reaches one at all. Exported for `layout.js`, which re-derives the
+// page frame a canvas presents, and for the suites that build a fixture frame
+// — the day that re-derivation goes, the export stands for the suites alone,
+// and they should take `geometry` rather than keep it standing.
+/** @type {(width: number, height: number, margin: number) => Frame} */
+export let frame = (width, height, margin) => ({
+  width,
+  height,
+  margin,
+  content: width - 2 * margin,
+  top: height - margin,
+  bottom: margin,
+});
+
 /**
  * The page box and the content box in one, for a render: the host's size,
  * and whichever margin the host and the opening event agreed on.
  *
- * @type {(page: any, opening?: any) => import('./canvas.js').Frame}
+ * @type {(page: any, opening?: any) => Frame}
  */
 export let geometry = (page = {}, opening) => {
   let { width, height } = pageBox(page, "options.page");

package/lib/paint.js

@@ -123,7 +123,9 @@ let loadFaces = async (fonts) => {
 };
 
 // Every bitmap decoded so far, by the bytes it was decoded from: one logo on
-// every page is decoded once.
+// every page is decoded once. A rejection is remembered too, so a file the
+// browser refused is refused from memory ever after — a caller repainting the
+// same page never pays for a second decode of bytes that will not decode.
 /** @type {WeakMap<Uint8Array, Promise<ImageBitmap>>} */
 let BITMAPS = new WeakMap();
 
@@ -204,17 +206,30 @@ let PAINTERS = { rect: paintRect, line: paintLine, text: paintText, mark: paintM
 
 /** @type {(ctx: CanvasRenderingContext2D, op: Op, bitmaps: Map<Op, ImageBitmap>) => void} */
 let paintOp = (ctx, op, bitmaps) => {
-  if (op.kind === "image")
-    ctx.drawImage(/** @type {ImageBitmap} */ (bitmaps.get(op)), op.x, op.y, op.w, op.h);
-  else PAINTERS[op.kind](ctx, op);
+  // An image with no bitmap did not decode, and is drawn as nothing. The map
+  // is the one place that is known: `decode` keeps no entry for a file the
+  // browser refused, so there is no second flag to read and no way to ask
+  // this question twice.
+  if (op.kind === "image") {
+    let bitmap = bitmaps.get(op);
+    if (bitmap) ctx.drawImage(bitmap, op.x, op.y, op.w, op.h);
+  } else PAINTERS[op.kind](ctx, op);
 };
 
-// Every image on the page, decoded together rather than one after another.
+// Every image on the page, decoded together rather than one after another,
+// and each settling on its own: gathering with `Promise.all` made one file the
+// browser refused the whole page's failure, thrown before the first draw op.
+// `paint`'s own doc says why that is the wrong price. An image that did not
+// decode has no entry here, which is how `paintOp` knows.
 /** @type {(page: Page) => Promise<Map<Op, ImageBitmap>>} */
 let decode = async (page) => {
   let images = page.ops.filter((op) => op.kind === "image");
-  let bitmaps = await Promise.all(images.map(bitmapOf));
-  return new Map(images.map((op, i) => [op, bitmaps[i]]));
+  let bitmaps = await Promise.all(images.map((op) => bitmapOf(op).catch(() => null)));
+  return new Map(
+    /** @type {[Op, ImageBitmap][]} */ (
+      images.map((op, i) => [op, bitmaps[i]]).filter(([, bitmap]) => bitmap)
+    ),
+  );
 };
 
 /**
@@ -230,6 +245,14 @@ let decode = async (page) => {
  * superseded call reach a canvas still on screen — which is what the viewer's
  * stage retires a page for (docs/adr/0046).
  *
+ * **An image the browser will not decode is drawn as nothing, and the page is
+ * drawn around it.** The engine vouched for the magic numbers and the layout
+ * read the size out of the header, so a file corrupt past that point is not
+ * known to be bad until here; costing the whole page for it — every other op
+ * and the marking with it — is a worse answer than costing the image. What is
+ * lost is what could not be drawn. A caller wanting the failure instead should
+ * decode before it paints.
+ *
  * @param {CanvasRenderingContext2D} ctx The context to paint on.
  * @param {Page} page One page of a `Layout`.
  * @param {{ scale?: number, fonts?: any }} [options]

package/lib/settings.js

@@ -0,0 +1,88 @@
+/**
+ * Everything that holds for a whole render and is not geometry — the render's
+ * `Settings`, and the one reading of what a report default amounts to.
+ *
+ * A `Frame` (canvas.js) is a page's geometry; a `Settings` is the other half:
+ * the faces to measure against, the report default narrowed to `base` and
+ * `family`, and the three intl facts a formatted value resolves in. A canvas
+ * holds one by reference, so a measuring canvas built for a probe reads exactly
+ * what the listing canvas reads and a band cannot be reserved against one
+ * locale and drawn in another. This module owns what a settings *is* and how a
+ * report's opening event becomes one; canvas.js draws with it, text.js measures
+ * against it, and neither has to know what `style.size` or `style.family`
+ * amount to.
+ */
+import { familyName } from "./fonts.js";
+import { sizeOf } from "./style.js";
+
+// This layout's baseline type size. Not a host option: a document's type size
+// is the document's own, so it is `style.size` on the report and the number
+// here is only what text renders at when nothing declares one. The XLSX target
+// carries the same 10 for the same reason (docs/adr/0014, docs/adr/0033).
+let BASE = 10;
+
+/**
+ * Everything that holds for a whole render and is not geometry: the faces to
+ * measure against, the report default narrowed to `family` and `size` (landing
+ * in `family` and `base` here), and the three intl facts a formatted value
+ * resolves in.
+ *
+ * A canvas holds one of these by reference, never a copy, which is the whole
+ * reason it is an object. A measuring canvas built off the same settings reads
+ * exactly what the listing canvas reads, so a page band cannot be reserved
+ * against one locale and drawn in another — an agreement that used to rest on
+ * a hand-written copy staying in step.
+ *
+ * `family` is null when the report declares none, and each of the intl three is
+ * undefined when the engine settled none.
+ *
+ * @typedef {{ fonts: import('./fonts.js').Fonts, base: number,
+ *   family: string | null, locale?: string, currency?: string,
+ *   timeZone?: string }} Settings
+ */
+
+/**
+ * The render's settings, complete by construction from the opening event the
+ * target already peeked. The report default 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. Reading the
+ * pair here is the whole of this target's reading of docs/adr/0033 — the default
+ * reaches a node as a fallback the settings carry, 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 this target's own baseline, so a
+ * default declaring one of the pair leaves the other at the baseline, and one
+ * whose value is unusable leaves the baseline standing.
+ *
+ * Built once and never settled again: these hold for a whole render, so there
+ * is no event that could set them a second time — a second settling is not
+ * refused, it is unexpressible. `opening` is null when the stream is empty (no
+ * report to read a default from), which yields the bare baseline: the target's
+ * own size, no family, and the intl three unset. Those three are read straight
+ * off the event whether or not it declares them — a formatted value is the only
+ * thing that reads them, and an empty stream produces none, so an unset one
+ * never reaches `Intl`.
+ *
+ * @param {import('./fonts.js').Fonts} fonts The loaded faces.
+ * @param {any} [opening] The peeked `report-start` event, or null.
+ * @returns {Settings}
+ */
+let settings = (fonts, opening) => {
+  let event = opening || {};
+  let style = event.style || {};
+  return {
+    fonts,
+    base: sizeOf(style, BASE),
+    family: familyName(style) || null,
+    locale: event.locale,
+    currency: event.currency,
+    timeZone: event.timeZone,
+  };
+};
+
+export { settings };

package/lib/style.js

@@ -69,8 +69,7 @@ let sizeOf = (style, base) => (Number.isFinite(style.size) && style.size > 0 ? s
 // Style blocks layer outward-in: row under cell, split under slot. Those are
 // the two innermost of the four layers; the outer two reach a node without
 // being merged into it -- the band-role default through `roled` below, and the
-// report default through the render's settings, as `canvas.js`'s
-// `adoptSettings` explains.
+// report default through the render's settings, as `settings.js` explains.
 /** @type {(under: any, over: any) => any} */
 let merge = (under, over) => (under ? (over ? { ...under, ...over } : under) : over || {});
 

package/lib/text.js

@@ -9,10 +9,10 @@ import { LEAD, col, dressed, sizeOf, upper } from "./style.js";
 
 // What measuring needs and no more, and it is exactly the render's settings:
 // the faces to measure against, the base size and family a style falls back to,
-// and the intl three a formatted value resolves in. Declared next door, in
-// `canvas.js`, where it is built and settled — nothing here can touch a page,
-// and a caller hands over `canvas.settings` rather than the canvas.
-/** @typedef {import('./canvas.js').Settings} Settings */
+// and the intl three a formatted value resolves in. Declared in `settings.js`,
+// the module that owns them; a caller hands over `canvas.settings` rather than
+// the canvas, so nothing here can touch a page.
+/** @typedef {import('./settings.js').Settings} Settings */
 
 /**
  * @typedef {{ text: string, font: any, size: number, color: any,
@@ -29,7 +29,7 @@ import { LEAD, col, dressed, sizeOf, upper } from "./style.js";
 /** @type {(token: any, style: any, settings: Settings) => string} */
 let rawOf = (token, style, settings) => {
   if ("literal" in token) return token.literal;
-  return format(token.value, style?.format, settings) ?? display(token.value);
+  return format(token.value, style, settings) ?? display(token.value);
 };
 
 // This layout has no text-transform to defer to, so `uppercase` is applied to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/layout",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The paged display list for quario — the layout the PDF target writes and the viewer paints — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -43,13 +43,13 @@
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/fontkit": "^2.0.9",
     "fontkit": "^2.0.4",
-    "quario": "^0.5.0",
+    "quario": "^0.6.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.5.0"
+    "quario": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {