@quario/layout 0.1.0

package/lib/fonts.js

@@ -0,0 +1,409 @@
+/**
+ * The faces a layout can measure with — the one measurer (docs/adr/0039).
+ *
+ * Nothing here can write a document. The base-14 families measure against the
+ * AFM metrics `@pdf-lib/standard-fonts` carries, over WinAnsi, which is what
+ * pdf-lib measures against when it writes the same face — so a line breaks
+ * where the PDF breaks it. A host-supplied TrueType family measures against
+ * fontkit's shaping of the same bytes the PDF target embeds. Every face is
+ * loaded before the walk starts, so resolving a style to one during layout
+ * stays synchronous.
+ *
+ * A face answers three questions: how wide a string is at a size, how far a
+ * line's top sits above its baseline, and which code points it can draw. A
+ * base-14 face answers a fourth — what each code point's advance is — which
+ * the list carries so a painter can correct for the screen face standing in
+ * for it. A host's own face is nobody's stand-in and answers only the three.
+ */
+import { Encodings, Font, FontNames } from "@pdf-lib/standard-fonts";
+
+// The three families the vocabulary names, four variants each, indexed by
+// `bold + 2 * italic` — the same ordering the schema's `bold`/`italic` flags
+// produce. Unknown family names fall back to sans, as SCHEMA.md specifies.
+let BASE = {
+  sans: [
+    FontNames.Helvetica,
+    FontNames.HelveticaBold,
+    FontNames.HelveticaOblique,
+    FontNames.HelveticaBoldOblique,
+  ],
+  serif: [
+    FontNames.TimesRoman,
+    FontNames.TimesRomanBold,
+    FontNames.TimesRomanItalic,
+    FontNames.TimesRomanBoldItalic,
+  ],
+  mono: [
+    FontNames.Courier,
+    FontNames.CourierBold,
+    FontNames.CourierOblique,
+    FontNames.CourierBoldOblique,
+  ],
+};
+
+/**
+ * Which face a piece of the list is set in: the family it resolved to, the
+ * variant index, and whether the bytes behind it came from the host. A painter
+ * maps the three to its own face — pdf-lib's embedded font, a CSS font string.
+ *
+ * `embedded` is the fact a painter cannot work out for itself. A host may map
+ * its own family onto `sans`, `serif` or `mono` (SCHEMA.md), so the family name
+ * does not say which kind of face this is, and the two kinds are drawn
+ * differently: a stand-in has to be corrected glyph by glyph, a host's own face
+ * must not be. See `paint.js`.
+ * @typedef {{ family: string, variant: number, embedded: boolean }} FaceRef
+ */
+/**
+ * `shape` belongs to the base-14 faces alone: it exists so a painter can
+ * correct a [stand-in face](../../../CONTEXT.md#stand-in-face), and nothing
+ * stands in for bytes the host supplied. So **a face has `shape` exactly when
+ * its ref says `embedded: false`** — one fact, and the two constructors below
+ * each settle both halves of it, because a face whose ref disagreed with its
+ * own `shape` would have the list promise a painter advances it never carries
+ * (or carry advances no painter will place).
+ * @typedef {{ ref: FaceRef,
+ *   widthOfTextAtSize: (text: string, size: number) => number,
+ *   heightAtSize: (size: number) => number,
+ *   getCharacterSet?: () => number[],
+ *   shape?: (text: string, size: number) => { advances: number[] } }} Face
+ */
+/** @typedef {{ families: Record<string, Face[]> }} Fonts */
+
+/** @type {(text: string) => string[]} */
+let codePoints = (text) => Array.from(text);
+
+// A base-14 face: AFM widths and kerning over WinAnsi. The width of a string
+// is the sum of its glyph widths plus the kerning between neighbours — the
+// same arithmetic pdf-lib's standard-font embedder does, kept in step so the
+// two measure alike. A glyph without a width is 250, as it is there.
+//
+// One glyph per code point, always: the text arrives WinAnsi-encodable because
+// `printable` substituted everything else, the encoding is a one-to-one table,
+// and there is no shaping to fold a pair into a ligature. That is what lets a
+// painter place these advances against the characters of the source string.
+/** @type {(family: string, variant: number, name: string) => Face} */
+let standard = (family, variant, name) => {
+  let ref = { family, variant, embedded: false };
+  let font = Font.load(/** @type {any} */ (name));
+  let encoding = Encodings.WinAnsi;
+  /** @type {(text: string) => { code: number, name: string }[]} */
+  let glyphs = (text) =>
+    codePoints(text).map((char) => encoding.encodeUnicodeCodePoint(char.codePointAt(0) ?? 0));
+  /** @type {(glyph: { name: string }, next?: { name: string }) => number} */
+  let advance = (glyph, next) =>
+    (font.getWidthOfGlyph(glyph.name) || 250) +
+    (next ? font.getXAxisKerningForPair(glyph.name, next.name) || 0 : 0);
+  let ascender = font.Ascender || font.FontBBox[3];
+  return {
+    ref,
+    widthOfTextAtSize: (text, size) => {
+      let list = glyphs(text);
+      let total = 0;
+      for (let [i, glyph] of list.entries()) total += advance(glyph, list[i + 1]);
+      return (total * size) / 1000;
+    },
+    heightAtSize: (size) => (ascender * size) / 1000,
+    getCharacterSet: () => encoding.supportedCodePoints,
+    shape: (text, size) => {
+      let list = glyphs(text);
+      return { advances: list.map((glyph, i) => (advance(glyph, list[i + 1]) * size) / 1000) };
+    },
+  };
+};
+
+// A TrueType face: fontkit's shaping of the bytes, measured in the font's own
+// units. pdf-lib shapes the same bytes with the same fontkit when it embeds
+// them and advances by the same widths, so the two agree.
+//
+// No `shape`. Shaping is not one glyph per code point here — a ligature folds
+// two characters into one glyph, an RTL run comes back in visual order, a
+// combining mark advances by nothing — so an advance array has no character to
+// belong to. A painter with these bytes draws the run whole and lets its own
+// shaper place the glyphs, which is what pdf-lib does too.
+/** @type {(family: string, variant: number, font: any) => Face} */
+let embedded = (family, variant, font) => {
+  let ref = { family, variant, embedded: true };
+  let scale = 1000 / font.unitsPerEm;
+  /** @type {(text: string) => any[]} */
+  let glyphs = (text) => font.layout(text).glyphs;
+  let ascender = (font.ascent || font.bbox.maxY) * scale;
+  return {
+    ref,
+    widthOfTextAtSize: (text, size) => {
+      let total = 0;
+      for (let glyph of glyphs(text)) total += glyph.advanceWidth * scale;
+      return (total * size) / 1000;
+    },
+    heightAtSize: (size) => (ascender * size) / 1000,
+    getCharacterSet: () => font.characterSet,
+  };
+};
+
+// The base-14 metrics are immutable, so the twelve AFM parses happen once per
+// process rather than once per render; each render still gets its own record,
+// since a host's families are added to it.
+/** @type {Record<string, Face[]> | null} */
+let base = null;
+/** @type {() => Record<string, Face[]>} */
+let baseFamilies = () =>
+  (base ??= Object.fromEntries(
+    Object.entries(BASE).map(([family, names]) => [
+      family,
+      names.map((name, variant) => standard(family, variant, name)),
+    ]),
+  ));
+
+// A render's own copy, so adding a host's families cannot reach the memo.
+/** @type {() => Record<string, Face[]>} */
+let loadBase = () => ({ ...baseFamilies() });
+
+/**
+ * The base-14 sans regular, whatever a host mapped `sans` to. Reached only by
+ * the marking, which is the one thing on a page a host's font mapping must not
+ * reach — see `stamp` in canvas.js.
+ */
+/** @type {() => Face} */
+export let baseSans = () => baseFamilies().sans[0];
+
+// Host-supplied TrueType families need a font parser, which is an optional
+// peer: base-14 reports install nothing extra. Loaded only when `fonts` is
+// passed, and a missing package is reported as what it is.
+/** @type {() => Promise<any>} */
+let useFontkit = async () => {
+  try {
+    return (await import("@pdf-lib/fontkit")).default;
+  } catch {
+    throw Error("options.fonts: install @pdf-lib/fontkit to measure TrueType families");
+  }
+};
+
+/** @type {(name: string, def: any) => string} */
+let asFamily = (name, def) => {
+  let path = "options.fonts." + name;
+  if (!def || typeof def !== "object")
+    throw Error(path + ": expected { regular, bold?, italic?, boldItalic? }");
+  if (def.regular == null) throw Error(path + ".regular: required");
+  return path;
+};
+
+/** The bytes a host handed over, whichever of the two shapes it used. */
+/** @type {(source: any) => Uint8Array} */
+export let bytesOf = (source) => (source instanceof Uint8Array ? source : new Uint8Array(source));
+
+/** @type {(fontkit: any, src: any, path: string, variant: string) => any} */
+let parseOne = (fontkit, src, path, variant) => {
+  try {
+    return fontkit.create(bytesOf(src[variant]));
+  } catch (e) {
+    throw Error(path + "." + variant + ": " + /** @type {Error} */ (e).message);
+  }
+};
+
+/**
+ * The four variants of a family in the order `FaceRef.variant` indexes them —
+ * `bold + 2 * italic` — which is the one fact every painter's registry has to
+ * share with the measurer's.
+ */
+export let VARIANTS = /** @type {const} */ (["regular", "bold", "italic", "boldItalic"]);
+
+// Every face built from a host's bytes so far, so a family passed on every
+// render is parsed once. The identity rule is `paint.js`'s `FACES`, to the
+// letter — change one and change the other, or the measurer and the painter
+// disagree about what a face is:
+//
+// • keyed on the host's own source object, never on `bytesOf(source)`, since
+//   a host may hand over an `ArrayBuffer` and `bytesOf` allocates a fresh
+//   view every call, so a bytes-keyed entry would never be found twice;
+// • the inner key carries family and variant, because a `Face` closes over
+//   its `ref`: one file aliased across two families, or given as both a
+//   family's regular and its bold, is two faces. A variant falling back to
+//   the family's regular is keyed here too, under the regular's source — so
+//   all four faces of a `regular`-only family are stable across renders, and
+//   `CHARSETS` below keeps that font's cmap rather than rebuilding the set
+//   every render.
+//
+// The cache is only as good as the host's object stability, which is what
+// `LayoutOptions.fonts` asks for. No promise caching, unlike `paint.js`:
+// parsing is synchronous, so the first caller past the `useFontkit` await
+// runs a whole family to completion before another resumes.
+/** @type {WeakMap<object, Map<string, Face>>} */
+let FACES = new WeakMap();
+
+/** @type {(source: object) => Map<string, Face>} */
+let registryOf = (source) => {
+  let registry = FACES.get(source);
+  if (!registry) FACES.set(source, (registry = new Map()));
+  return registry;
+};
+
+/** @type {(source: any, key: string, make: () => Face) => Face} */
+let remembered = (source, key, make) => {
+  // A source that is not an object cannot be a `WeakMap` key. `asFamily` only
+  // proves `regular` is present, so a host may still hand over a path string
+  // or a number; those go straight to `make`, which reports them as the
+  // located `options.fonts.<name>.<variant>` mistake they are rather than as
+  // a raw "invalid value used as weak map key".
+  if (!source || typeof source !== "object") return make();
+  let registry = registryOf(source);
+  let face = registry.get(key);
+  // The entry is written after `make`, never before: a parse that throws is a
+  // host mistake that fails the render, so there is no hot path to protect and
+  // no rejection to reason about on a later one.
+  if (!face) registry.set(key, (face = make()));
+  return face;
+};
+
+// Missing variants fall back to the family's regular, so a face is always
+// resolvable once the family is named.
+/** @type {(fontkit: any, name: string, def: any) => Face[]} */
+let familyOf = (fontkit, name, def) => {
+  let path = asFamily(name, def);
+  let family = name.toLowerCase();
+  /** @type {Face[]} */
+  let faces = [];
+  for (let [variant, key] of VARIANTS.entries())
+    faces.push(
+      remembered(def[key] ?? def.regular, family + "/" + variant, () =>
+        def[key] == null
+          ? { ...faces[0], ref: { ...faces[0].ref, variant } }
+          : embedded(family, variant, parseOne(fontkit, def, path, key)),
+      ),
+    );
+  return faces;
+};
+
+/** @type {(custom: any, families: Record<string, Face[]>) => Promise<void>} */
+let loadCustom = async (custom, families) => {
+  if (!(custom && Object.keys(custom).length)) return;
+  let fontkit = await useFontkit();
+  for (let [name, def] of Object.entries(custom))
+    families[name.toLowerCase()] = familyOf(fontkit, name, def);
+};
+
+/**
+ * Load every face a layout can reach and return the registry `face()` reads.
+ *
+ * @param {any} custom `options.fonts`, or null.
+ * @returns {Promise<Fonts>}
+ */
+export async function loadFonts(custom) {
+  let families = loadBase();
+  await loadCustom(custom, families);
+  return { families };
+}
+
+/**
+ * Check the shape of a host's font mapping without loading a parser: the
+ * factory call is where a malformed option is reported.
+ *
+ * @param {any} custom `options.fonts`, or null.
+ */
+export let checkFonts = (custom) => {
+  if (custom == null) return;
+  if (typeof custom !== "object") throw Error("options.fonts: expected a record of families");
+  for (let [name, def] of Object.entries(custom)) asFamily(name, def);
+};
+
+// What a declared `family` normalises to before it is looked up: lower case,
+// and nothing at all when the value is not a name. Exported because the report
+// default is normalised once per render rather than once per cell, and two
+// spellings of this would drift.
+/** @type {(style: any) => string} */
+export let familyName = (style) =>
+  typeof style.family === "string" ? style.family.toLowerCase() : "";
+
+// Own-key lookup: the family name is render data, so `constructor` must
+// fall back to sans rather than resolve an inherited member.
+/** @type {(fonts: Fonts, name: string | null) => Face[]} */
+let variantsOf = (fonts, name) =>
+  name && Object.hasOwn(fonts.families, name) ? fonts.families[name] : fonts.families.sans;
+
+/** @type {(style: any) => number} */
+let faceIndex = (style) => (style.bold ? 1 : 0) | (style.italic ? 2 : 0);
+
+/**
+ * Resolve a style block to one face.
+ *
+ * `fallback` is the report default's family, which the canvas carries for the
+ * whole render (docs/adr/0033) — so text declaring no family is set in the
+ * document's.
+ *
+ * The fallback turns on whether a family was *declared*, never on whether the
+ * declared one resolves: a literal `family` is a non-empty string by the time
+ * the engine passes it, but an `=` expression is resolved at render and
+ * reaches here unchecked, so an item can declare `""`, a number or `null`.
+ * Those are the item's own declaration and fall to sans like any other name
+ * this layout cannot resolve (SCHEMA.md) — the document's family is for text
+ * that declared none. Own-key, because the block is render data.
+ *
+ * @type {(fonts: Fonts, style: any, fallback: string | null) => Face}
+ */
+export function face(fonts, style, fallback) {
+  let declared = Object.hasOwn(style, "family");
+  return variantsOf(fonts, declared ? familyName(style) : fallback)[faceIndex(style)];
+}
+
+// The distance from a line's top to its baseline: the face's ascender.
+/** @type {(font: Face, size: number) => number} */
+export let ascOf = (font, size) => font.heightAtSize(size);
+
+// Text measurement, against the face's own metrics.
+/** @type {(font: Face, text: string, size: number) => number} */
+export let width = (font, text, size) => font.widthOfTextAtSize(text, size);
+
+// Printable ASCII, which every text face encodes and which almost all report
+// text is. Asking the cmap instead costs a set walk per atom.
+let ASCII = /^[\x20-\x7E]*$/;
+
+// A face's character set is its cmap: WinAnsi code points on the base-14,
+// fontkit's characterSet on an embedded TrueType. A face with no cmap (the
+// layout suite's measuring doubles) does not substitute: width is its whole
+// contract.
+let CHARSETS = new WeakMap();
+let OPEN = { has: () => true };
+
+/** @typedef {{ has: (code: number) => boolean }} Cmap */
+
+/** @type {(font: any) => Cmap} */
+let charsetOf = (font) => {
+  let set = CHARSETS.get(font);
+  if (set) return set;
+  set = typeof font.getCharacterSet === "function" ? new Set(font.getCharacterSet()) : OPEN;
+  CHARSETS.set(font, set);
+  return set;
+};
+
+/**
+ * Replace characters a face cannot draw with `?`.
+ *
+ * Cell text is untrusted data, so one stray character must not fail the
+ * render: SCHEMA.md promises `?` for any face — WinAnsi on the base-14, the
+ * cmap on an embedded TrueType. A face that also lacks `?` omits the
+ * character rather than drawing .notdef.
+ *
+ * The ASCII guard carries the common case; only text with a character
+ * outside it pays for the cmap walk. Printable ASCII is a subset of WinAnsi
+ * and of every text face this layout measures.
+ *
+ * @type {(font: any, text: string) => string}
+ */
+export let printable = (font, text) => {
+  if (!text || ASCII.test(text) || encodable(font, text)) return text;
+  return replaceUndrawable(charsetOf(font), text);
+};
+
+/** @type {(set: Cmap, text: string) => string} */
+let replaceUndrawable = (set, text) => {
+  let sub = set.has(0x3f) ? "?" : "";
+  // Encodedness is a per-code-point question, so that is the unit to ask it
+  // in — the grapheme clusters the rule protects are undrawable anyway.
+  return codePoints(text)
+    .map((char) => (set.has(char.codePointAt(0) ?? -1) ? char : sub))
+    .join("");
+};
+
+/** @type {(font: any, text: string) => boolean} */
+let encodable = (font, text) => {
+  let set = charsetOf(font);
+  return codePoints(text).every((char) => set.has(char.codePointAt(0) ?? -1));
+};

package/lib/image.js

@@ -0,0 +1,58 @@
+/**
+ * An image's own size, read from its header. Sizing is a fact about the bytes
+ * rather than anything a page can answer, so it sits here and not on the
+ * drawing surface: the band flow asks for it while measuring, where no
+ * document is in reach at all, and again while drawing, where one is.
+ *
+ * Read, never decoded — a PNG's IHDR and a JPEG's frame header carry the two
+ * numbers the layout needs, and nothing else here looks at a pixel.
+ *
+ * The XLSX target reads the same two headers for its own placement, in pixels.
+ * Whether that fact belongs on the engine's event instead — it already reads
+ * the magic numbers to name the format — is bead `quario-b0h`.
+ */
+
+// Points, at the conventional 96 dpi the schema names: 72/96 of a pixel.
+let PER_PX = 72 / 96;
+
+/** @type {(bytes: Uint8Array, at: number) => number} */
+let word = (bytes, at) => (bytes[at] << 8) | bytes[at + 1];
+
+/** @type {(code: number) => boolean} */
+let inSof = (code) => code >= 0xc0 && code <= 0xcf;
+
+/** @type {(code: number) => boolean} */
+let notTable = (code) => code !== 0xc4 && code !== 0xc8 && code !== 0xcc;
+
+// The frame header carries the dimensions, and it is the first SOFn marker:
+// every code in C0..CF except the three in that range that are not frames --
+// DHT, the JPG extension, and DAC.
+/** @type {(code: number) => boolean} */
+let isFrame = (code) => inSof(code) && notTable(code);
+
+/** @type {(bytes: Uint8Array) => { w: number, h: number }} */
+let jpegSize = (bytes) => {
+  for (let at = 2; at + 9 < bytes.length; at += 2 + word(bytes, at + 2)) {
+    if (bytes[at] !== 0xff) break;
+    if (isFrame(bytes[at + 1])) return { w: word(bytes, at + 7), h: word(bytes, at + 5) };
+  }
+  return { w: 0, h: 0 };
+};
+
+/**
+ * The image's intrinsic size in points. The format is the engine's sniff,
+ * riding on the event, so nothing here decides it a second time.
+ *
+ * @param {Uint8Array} bytes The image file.
+ * @param {string} format The engine's sniff: `"png"` or `"jpeg"`.
+ * @returns {{ w: number, h: number }} The size, in points.
+ */
+export let intrinsic = (bytes, format) => {
+  // A PNG carries the two numbers in its IHDR at a fixed offset.
+  let { w, h } = format === "png" ? { w: word(bytes, 18), h: word(bytes, 22) } : jpegSize(bytes);
+  // 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");
+  return { w: w * PER_PX, h: h * PER_PX };
+};

package/lib/index.d.ts

@@ -0,0 +1,220 @@
+import type { Target } from "quario";
+
+/** Page geometry, in PostScript points. Host configuration, never schema. */
+export interface LayoutPage {
+  /** Named size or `[width, height]` in points. Default `'A4'`. */
+  size?: "A4" | "letter" | [number, number];
+  /** Margin on all four sides, in points. Default `54` (0.75 in). */
+  margin?: number;
+}
+
+/** One TrueType family; missing variants fall back to `regular`. */
+export interface LayoutFontFamily {
+  regular: Uint8Array | ArrayBuffer;
+  bold?: Uint8Array | ArrayBuffer;
+  italic?: Uint8Array | ArrayBuffer;
+  boldItalic?: Uint8Array | ArrayBuffer;
+}
+
+/** The font mapping: a declared `family` name to the bytes it measures against. */
+export type LayoutFonts = Record<string, LayoutFontFamily>;
+
+/** Host controls, taken and validated at the factory call. */
+export interface LayoutOptions {
+  page?: LayoutPage;
+  /**
+   * TrueType families to measure against, selected from styles by
+   * `family: '<name>'`. Pass the same record to `pdf({ fonts })` and to
+   * `paint()`, so preview and document break their lines in the same places
+   * and draw in the same faces. Requires the optional peer `@pdf-lib/fontkit`;
+   * the base-14 families need nothing extra.
+   *
+   * Hold the record and the buffers in it across renders rather than building
+   * them anew each time: they are the identity a face is remembered by, so a
+   * host that hands over a fresh buffer parses the file again to measure
+   * against it, and registers a fresh face to draw it with.
+   */
+  fonts?: LayoutFonts;
+}
+
+/** A colour on the list: three channels in `0..1`. */
+export interface Color {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * Which face a run is set in: the family it resolved to (`sans`, `serif`,
+ * `mono`, or a lower-cased name from the font mapping), the variant index
+ * `bold + 2 * italic`, and whether the face is bytes the host supplied.
+ *
+ * `embedded` is not derivable from the family name — a host may map its own
+ * family onto `sans`, `serif` or `mono` — and it decides how a painter draws
+ * the run. See `TextOp.advances`.
+ */
+export interface FaceRef {
+  family: string;
+  variant: number;
+  embedded: boolean;
+}
+
+/** A filled rectangle. */
+export interface RectOp {
+  kind: "rect";
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  color: Color;
+}
+
+/** A stroked segment: a border side, a rule, a text decoration. */
+export interface LineOp {
+  kind: "line";
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  width: number;
+  color: Color;
+  dash: number[] | null;
+}
+
+/** An image, placed. `bytes` is the array the source expression yielded. */
+export interface ImageOp {
+  kind: "image";
+  bytes: Uint8Array;
+  format: "png" | "jpeg";
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * One run of text: `y` is the line's top and `asc` how far below it the
+ * baseline sits, and `text` is the string to draw.
+ *
+ * `advances` rides only where a painter can use it — one advance in points per
+ * code point of `text`, present exactly when `font.embedded` is false. A
+ * base-14 family is drawn with them, character by character, so the face
+ * standing in for it on screen cannot drift across the run. A host's own
+ * family carries none: the painter has the same bytes the layout measured, so
+ * it draws the run whole and its own shaping is the document's.
+ */
+export interface TextOp {
+  kind: "text";
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  asc: number;
+  size: number;
+  font: FaceRef;
+  color: Color;
+  text: string;
+  advances?: number[];
+}
+
+/**
+ * The unlicensed marking (LICENSE section 6), one per page, drawn last:
+ * `x`/`y` start its baseline and `angle` turns it counter-clockwise, in
+ * degrees.
+ */
+export interface MarkOp {
+  kind: "mark";
+  x: number;
+  y: number;
+  angle: number;
+  size: number;
+  font: FaceRef;
+  text: string;
+}
+
+export type Op = RectOp | LineOp | ImageOp | TextOp | MarkOp;
+
+/**
+ * The rectangle one schema node was drawn in, named by its path. One node
+ * draws many boxes — a column's cell on every row, a header on every page it
+ * repeats on — and every one of them means that node.
+ */
+export interface Box {
+  path: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * One page of the list. Coordinates are points from the page's top-left
+ * corner, `y` descending; `number` and `total` are what `page.number` and
+ * `page.total` read on it.
+ */
+export interface Page {
+  number: number;
+  total: number;
+  width: number;
+  height: number;
+  ops: Op[];
+  boxes: Box[];
+}
+
+/** An outline entry: a group instance, and where its content begins. */
+export interface Mark {
+  title: string;
+  depth: number;
+  page: number;
+  x: number;
+  y: number;
+}
+
+/** The display list: every page of the document, laid out. */
+export interface Layout {
+  width: number;
+  height: number;
+  pages: Page[];
+  /** The group tree, in document order — the PDF target's bookmarks. */
+  marks: Mark[];
+}
+
+/**
+ * The layout target:
+ * `quario().report(schema).render(layout({ page }), data)` resolves the
+ * display list the PDF target writes and the viewer paints
+ * (docs/adr/0039).
+ */
+export function layout(options?: LayoutOptions): Target<"layout", Promise<Layout>>;
+
+/**
+ * CSS pixels per point at 100%: 96 dpi over PostScript's 72. Every surface
+ * that shows a page shows it at this size; a zoom is a factor on top of it.
+ */
+export const PX_PER_POINT: number;
+
+/**
+ * Paint one page onto a Canvas 2D context: a white page, then every op in
+ * order. `scale` is device pixels per point. `fonts` is the same record
+ * given to `layout()`, so a TrueType family draws in its own face.
+ */
+export function paint(
+  ctx: CanvasRenderingContext2D,
+  page: Page,
+  options?: { scale?: number; fonts?: LayoutFonts },
+): Promise<void>;
+
+/**
+ * The schema node drawn at a point on a page — the smallest box containing
+ * it — or `null` where nothing was drawn. Points from the top-left corner.
+ */
+export function hit(page: Page, x: number, y: number): Box | null;
+
+/**
+ * The page box a `page` option describes, validated: width, height and
+ * margin in points. `at` prefixes a failure with the option's name.
+ */
+export function pageBox(
+  page?: LayoutPage,
+  at?: string,
+): { width: number; height: number; margin: number };