@quario/layout 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-07
+
+### Added
+
+- **Per-run typography, decoration and highlights.** A styled run resolves its
+  own face, size and colour, and a line takes the largest size among its runs.
+  `underline` and `strikethrough` are drawn per run — over that run's width, in
+  that run's colour — where they used to stroke the whole line in the first
+  piece's colour. A run's `background` paints a highlight rectangle behind its
+  text; a cell's own background is still painted once, at cell scope.
+
+- **`checkFonts` is public.** It checks the shape of a `fonts` mapping without
+  loading a parser, and takes an optional name to prefix a failure with, the
+  way `pageBox` does — so a surface validating its own `fonts` property can
+  report the mistake against that property rather than against
+  `options.fonts`.
+
+### Fixed
+
+- **An outline `Mark` carries only what it declares.** Every mark shipped an
+  extra `titled` boolean — bookkeeping for whether a header had claimed the
+  entry — which was never part of the `Mark` interface and which nothing
+  reads. It is the open group instance's own state now, and no longer travels
+  on the object a consumer receives.
+
+## [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, 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,
@@ -119,27 +71,55 @@ let settings = (fonts) => ({ fonts, base: BASE, family: null });
  */
 let blank = (box, render) => ({ ...box, settings: render, y: 0, fresh: true });
 
-// Text decoration in the text colour. Thickness and offset come from the
-// line's ascender (the face metric already measured for baseline placement).
-// Empty lines (no width) draw nothing. Shared by the listing adapter and the
-// layout suite's recorder so both exercise the same path.
-/** @type {(line: Line) => Color} */
-let ink = (line) => (line.pieces[0] && line.pieces[0].color) || BLACK;
+// A styled run's `background`, painted behind its text as a highlight over
+// that run's width and the line's full height -- the same rectangle a cell's
+// own background is, one stretch narrower. All of a line's highlights are
+// painted before any of its glyphs, so a rectangle behind one run can never
+// land on top of the run before it. Shared with the layout suite's recorder
+// for the reason `decorateLine` is.
+/**
+ * @type {(rect: (color: Color, x: number, y: number, w: number, h: number) => void,
+ *   line: Line, left: number, yTop: number) => void}
+ */
+let highlightLine = (rect, line, left, yTop) => {
+  let cursor = left;
+  for (let piece of line.pieces) {
+    if (piece.bg) rect(piece.bg, cursor, yTop - line.h, piece.w, line.h);
+    cursor += piece.w;
+  }
+};
 
-/** @type {(line: Line) => boolean} */
-let wantsDeco = (line) => !!line.w && dressed(line);
+// Text decoration, drawn per piece: over that piece's width, in that piece's
+// colour. A rule across the whole line in the first piece's colour is what
+// this used to be, and it is exactly what "underline a word" cannot mean
+// (ADR 0061). Thickness and offset stay the line's, from the ascender already
+// measured for baseline placement, so one line's rules sit at one height
+// whatever sizes it mixes. Empty lines (no width) draw nothing. Shared by the
+// listing adapter and the layout suite's recorder so both exercise the same
+// path.
+/**
+ * @type {(stroke: (x1: number, x2: number, y: number, thickness: number, color: Color) => void,
+ *   piece: Line['pieces'][number], line: Line, left: number, baseline: number) => void}
+ */
+let decoratePiece = (stroke, piece, line, left, baseline) => {
+  let thickness = Math.max(line.asc / 12, 0.5);
+  let right = left + piece.w;
+  let color = piece.color || BLACK;
+  if (piece.underline) stroke(left, right, baseline - line.asc * 0.12, thickness, color);
+  if (piece.strikethrough) stroke(left, right, baseline + line.asc * 0.35, thickness, color);
+};
 
 /**
  * @type {(stroke: (x1: number, x2: number, y: number, thickness: number, color: Color) => void,
  *   line: Line, left: number, baseline: number) => void}
  */
 let decorateLine = (stroke, line, left, baseline) => {
-  if (!wantsDeco(line)) return;
-  let thickness = Math.max(line.asc / 12, 0.5);
-  let right = left + line.w;
-  let color = ink(line);
-  if (line.underline) stroke(left, right, baseline - line.asc * 0.12, thickness, color);
-  if (line.strikethrough) stroke(left, right, baseline + line.asc * 0.35, thickness, color);
+  if (!line.w) return;
+  let cursor = left;
+  for (let piece of line.pieces) {
+    decoratePiece(stroke, piece, line, cursor, baseline);
+    cursor += piece.w;
+  }
 };
 
 /**
@@ -182,9 +162,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
@@ -217,6 +200,7 @@ let listing = (box, render) => {
   /** @type {Canvas['drawLine']} */
   let drawLine = (line, x, yTop, avail, align) => {
     let left = x + shift(align, avail - line.w);
+    highlightLine(rect, line, left, yTop);
     let cursor = left;
     for (let piece of line.pieces) {
       writePiece(piece, line, cursor, yTop);
@@ -314,42 +298,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 +336,4 @@ let stamp = (canvas, text) => {
   };
 };
 
-export { adopt, adoptSettings, decorateLine, frame, listing, measuring, settings, stamp };
+export { adopt, decorateLine, highlightLine, listing, measuring, stamp };

package/lib/fonts.js

@@ -161,9 +161,9 @@ let useFontkit = async () => {
   }
 };
 
-/** @type {(name: string, def: any) => string} */
-let asFamily = (name, def) => {
-  let path = "options.fonts." + name;
+/** @type {(name: string, def: any, at: string) => string} */
+let asFamily = (name, def, at) => {
+  let path = at + "." + name;
   if (!def || typeof def !== "object")
     throw Error(path + ": expected { regular, bold?, italic?, boldItalic? }");
   if (def.regular == null) throw Error(path + ".regular: required");
@@ -241,7 +241,9 @@ let remembered = (source, key, make) => {
 // resolvable once the family is named.
 /** @type {(fontkit: any, name: string, def: any) => Face[]} */
 let familyOf = (fontkit, name, def) => {
-  let path = asFamily(name, def);
+  // Always the factory's own option here: loading happens behind `layout()`,
+  // and a surface that named it something else has already validated it.
+  let path = asFamily(name, def, "options.fonts");
   let family = name.toLowerCase();
   /** @type {Face[]} */
   let faces = [];
@@ -278,15 +280,23 @@ export async function loadFonts(custom) {
 }
 
 /**
- * Check the shape of a host's font mapping without loading a parser: the
- * factory call is where a malformed option is reported.
+ * Check the shape of a host's font mapping without loading a parser.
+ *
+ * `at` names the property in the message, the way `pageBox` takes one: the
+ * factory call reports `options.fonts`, but a surface element validating its
+ * own `fonts` property before any render has a different name for the same
+ * value, and a host mistake is named on the property that carries it.
+ *
+ * Only the shape. A face that will not parse, or a missing parser, is found
+ * while the report is measured and is a render failure there.
  *
  * @param {any} custom `options.fonts`, or null.
+ * @param {string} [at] What to call it in the message.
  */
-export let checkFonts = (custom) => {
+export let checkFonts = (custom, at = "options.fonts") => {
   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);
+  if (typeof custom !== "object") throw Error(at + ": expected a record of families");
+  for (let [name, def] of Object.entries(custom)) asFamily(name, def, at);
 };
 
 // What a declared `family` normalises to before it is looked up: lower case,

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;
@@ -224,3 +232,13 @@ export function pageBox(
   page?: LayoutPage,
   at?: string,
 ): { width: number; height: number; margin: number };
+
+/**
+ * Check the shape of a `fonts` mapping, throwing where it is malformed. `at`
+ * prefixes a failure with the option's name, so a surface validating its own
+ * `fonts` property names that rather than `options.fonts`.
+ *
+ * Only the shape: a face that will not parse, or a missing parser, is found
+ * while the report is measured and is a render failure there.
+ */
+export function checkFonts(fonts?: LayoutFonts | null, at?: string): void;

package/lib/index.js

@@ -21,13 +21,15 @@
  * 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";
+export { checkFonts } from "./fonts.js";
 
 // The options are described once, in the hand-written public declarations, and
 // read back here — a second copy in JSDoc is a copy that drifts.
@@ -78,8 +80,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 +95,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,