@quario/layout 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,22 +1,94 @@
-# Changelog
-
-All notable changes to @quario/layout are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.3.0] - 2026-09-07
-
-### Added
+# @quario/layout
+
+## 0.5.0
+
+### Minor Changes
+
+- **An image's box is now as wide as the container it sits in.** A
+  `background` or `border*` on an image item hugged the picture and now spans
+  the content width — or the slot's share inside a split — with `fit` sizing
+  the picture and `align` placing it inside, the way a text item's box has
+  always been drawn. The picture itself does not move. Breaking: a report that
+  relied on a border hugging a logo now draws that border across the full
+  width, and no declaration asks for the old shape.
+- **A page of the display list no longer carries `width` and `height`.** Read
+  the list's own `width` and `height` instead: they are the paper every page of
+  the report is drawn on, and every page's pair was a copy of them. A report has
+  one page size for the whole render — that has always been so, and page size is
+  a target option rather than something a document declares — so a page is
+  identified and positioned, and asked nothing about its size. A page now
+  carries `{ number, total, ops, boxes }`.
+
+  If you consume the list yourself, the fix is one substitution:
+
+  ```js
+  canvas.width = list.width * 2; // was list.pages[i].width * 2
+  canvas.height = list.height * 2; // was list.pages[i].height * 2
+  ```
+
+  `paint()` is unchanged in shape — it still takes one page — and it now fills
+  the white over the whole canvas rather than over the page's own rectangle.
+  **Size the canvas to the page before you call it**, as the sizing example above
+  does: the ops are in the page's own coordinates, so a canvas short of the paper
+  clips them whatever the fill covers. That was always so; it is now written down
+  in the README and on `paint()` itself.
+
+- **`Layout.pages` is typed as a non-empty list.** A render always lays out at
+  least one page — the first page opens whether or not anything renders on it —
+  so `pages[0]` no longer needs a check for a list that cannot exist. Runtime
+  behaviour is unchanged; this only states in the type what was already true.
+- **`Paper`** — the page box a report is drawn on, `{ width, height }` in points,
+  and what a display list's own `width` and `height` are. `Layout` extends it, so
+  `list.width` is unchanged and the pair now has a name to refer to.
+
+### Patch Changes
+
+- **A page's right and bottom edge could be left unpainted.** Where a caller
+  rounds the backing store up to a whole device pixel — A4 at 100% asks for
+  793.71 and takes 794 — `paint()` filled its white over the page's exact
+  rectangle and left the fraction past it transparent. On a canvas with white
+  behind it that is invisible; on one without, a hairline of whatever is behind
+  the canvas showed along two edges. The fill now covers the whole canvas.
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - quario@0.8.0
+
+## 0.4.0
+
+### Minor Changes
+
+- **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`.
+- **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
+
+### Minor Changes
 
 - 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
@@ -27,7 +99,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
@@ -35,15 +106,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
@@ -52,9 +119,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **A spanning cell is drawn as one box** across the columns it covers,
   starting where the first of them starts. It takes no part in allocating their
@@ -62,21 +129,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   empty table still shows its geometry. A spanning row too tall for the page it
   is on slices like any other, each slice following the geometry of the page or
   page-column strip it lands in.
-
 - **`valign`** places a cell's lines, or a slot's lines or picture, in the slack
   its row or split leaves over its own content: middle halves it, bottom takes
   it. The box does not move, and a picture is not scaled. A row too tall for
   any page, sliced across pages, paints from the top.
-
-### Changed
-
 - **A row's box is drawn by the row's cells.** A box declared on a table row
   used to be one rect across the summed column widths; it is now each covered
   cell's own, so a row's `borderBottom` still reads as one continuous edge
   while a row's `borderLeft` becomes an edge on every cell rather than one at
   the row's outer left. A row's border also occupies height now, as a cell's
   always has, so a bordered row is taller by its border's width.
-
 - **Measuring TrueType families now needs `fontkit`, not `@pdf-lib/fontkit`.**
   Install `fontkit` instead; nothing else about `options.fonts` changes. The
   old package's bundle crashed with a bare `ReferenceError` on any OpenType
@@ -85,9 +147,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   besides. Those faces now measure where they used to throw. Which scripts a
   face supports remains the font's and the parser's to answer, not this
   package's.
-
-### Fixed
-
 - **A group header no longer strands above a split.** A split cannot be broken
   across a page, so a header that introduces one has to keep the whole of it
   company — but the keep-together test measured a split by its first two lines
@@ -102,9 +161,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   always has before content no page can hold: it degrades to plain paginated
   flow and repeats nothing.
 
-## [0.1.0] - 2026-09-03
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **The paged display list.** `layout({ page, fonts })` is a render target
   resolving every page of the report — ops in points from the top-left, one
@@ -112,12 +171,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   marks, and on an unlicensed render the marking. The algorithm is the PDF
   target's typesetter, with its home moved here so a preview can paint the
   same pages the document has.
-
 - **One measurer.** Base-14 families measure against `@pdf-lib/standard-fonts`'
   AFM metrics over WinAnsi, TrueType families against `@pdf-lib/fontkit`'s
   shaping of the same bytes the PDF embeds, so a preview breaks its lines
   where the document breaks them.
-
 - **A box survives a page break.** An item or table row no page can hold
   whole is drawn as slices, and a slice carries the box sides the break left
   it: the top belongs to the first slice, the bottom to the last, and left and
@@ -126,7 +183,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   short one draws. Each slice reserves the bottom padding it may yet owe, so
   that edge stays above the bottom margin, and each carries a hit box, so an
   item that breaks is selectable on every page it reaches.
-
 - **`paint` and `hit`.** A Canvas 2D painter for one page, and the hit-test
   that maps a point on a page back to the schema node drawn there.
 
@@ -145,13 +201,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`pageBox`.** The page-size table and its validation, in one home for the
   PDF target, the viewer and the editor.
-
 - **`PX_PER_POINT`.** How big a point is on screen — 96 dpi over PostScript's
   72 — so every surface that shows a page shows it at the same size, and a
   zoom is a factor on top of it.
-
-### Changed
-
 - **A split slot's box now fills the split's height.** Before, a slot's
   background and border were exactly as tall as that slot's own content and
   padding asked for, so any slot shorter than the tallest one drew a box that
@@ -164,13 +216,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   does, and a slot's hit box follows its painted one. A report that relied on
   the short box — a slot background used as a chip beside taller content —
   now draws it full height; give that content a narrower slot of its own.
-
 - **A date string under `format: "date"` now presents as a date.** The text
   join presents the kind through the engine's `format()` helper, which now
   revives the two read forms. See the `quario` changelog for the forms.
-
-### Fixed
-
 - **A nested group's footer keeps the page columns.** Inside a page-column
   region, the first footer of a group nested in it ended the region: the
   strips collapsed and every band after it was laid out across the page, as

package/README.md

@@ -38,8 +38,9 @@ list.pages[0].ops; // what to draw on the first page, in order
 list.pages[0].boxes; // which schema node was drawn where
 ```
 
-Every coordinate is in PostScript points from the page's top-left corner. A page carries its
-`{ number, total }`, its ops — `rect`, `line`, `image`, `text` (the string to draw, the face
+Every coordinate is in PostScript points from the page's top-left corner. `list.width` and
+`list.height` are the paper every page is drawn on — a report has one, so a page does not carry its
+own size. A page carries its `{ number, total }`, its ops — `rect`, `line`, `image`, `text` (the string to draw, the face
 it is set in, and — for a built-in family only — the per-character advances the measurer laid it
 out with) and, on an unlicensed render, one `mark` — and its `boxes`, one per schema node drawn,
 named by the node's path.
@@ -61,14 +62,16 @@ import { hit, paint } from "@quario/layout";
 
 const canvas = document.querySelector("canvas");
 const page = list.pages[0];
-canvas.width = page.width * 2; // 2 device pixels per point
-canvas.height = page.height * 2;
+canvas.width = list.width * 2; // 2 device pixels per point
+canvas.height = list.height * 2;
 await paint(canvas.getContext("2d"), page, { scale: 2, fonts });
 
 hit(page, x, y); // -> { path, x, y, w, h } or null
 ```
 
-`paint` draws a white page and every op in order. Images are decoded from the bytes on the list —
+`paint` draws a white page and every op in order. Size the canvas to the page before you call it:
+the ops are in the page's own coordinates, so a smaller canvas clips them, and the white is filled
+over the whole canvas. Images are decoded from the bytes on the list —
 no `img-src` grant, no URLs. `hit` answers which schema node was drawn at a point: the smallest box
 containing it.
 
@@ -85,9 +88,16 @@ positioning, so a browser may kern by a fraction more. Where a line breaks, how
 and where a page ends are the layout's — one measurer, so preview and document agree.
 
 `PX_PER_POINT` is how big a point is on screen — 96 dpi over PostScript's 72 — so a surface showing
-a page at 100% sizes its canvas `page.width * PX_PER_POINT` CSS pixels wide and paints at
+a page at 100% sizes its canvas `list.width * PX_PER_POINT` CSS pixels wide and paints at
 `PX_PER_POINT * devicePixelRatio`. Any zoom is a factor on top of that.
 
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare, and
+[`@quario/layout`](https://getquario.com/docs/reference/layout/) is this package's own API.
+
 ## License
 
 quario is commercial software; evaluation is free and fully featured, with output marked as

package/lib/canvas.js

@@ -24,7 +24,7 @@
  * `y` descending, the way a screen reads. Points throughout.
  */
 import { baseSans } from "./fonts.js";
-import { BLACK, dressed, shift } from "./style.js";
+import { BLACK, shift } from "./style.js";
 
 /** @typedef {import('./page.js').Frame} Frame */
 /** @typedef {import('./text.js').Line} Line */
@@ -71,27 +71,55 @@ import { BLACK, dressed, shift } from "./style.js";
  */
 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;
+  }
 };
 
 /**
@@ -112,7 +140,10 @@ let listing = (box, render) => {
 
   // Open a fresh page and put the cursor at its top.
   let newPage = () => {
-    page = { width: canvas.width, height: canvas.height, ops: [], boxes: [] };
+    // No geometry: the paper is the list's, written once from this canvas's
+    // own frame, because the page box is fixed for the whole document (ADR
+    // 0069). A page carries what is per-page.
+    page = { ops: [], boxes: [] };
     pages.push(page);
     canvas.y = canvas.top;
     canvas.fresh = true;
@@ -172,6 +203,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);
@@ -307,4 +339,4 @@ let stamp = (canvas, text) => {
   };
 };
 
-export { adopt, decorateLine, listing, measuring, 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/index.d.ts

@@ -159,12 +159,13 @@ export interface Box {
  * 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.
+ *
+ * A page carries what is per-page and nothing else: the `Paper` it is drawn on
+ * is the list's (ADR 0069).
  */
 export interface Page {
   number: number;
   total: number;
-  width: number;
-  height: number;
   ops: Op[];
   boxes: Box[];
 }
@@ -178,11 +179,23 @@ export interface Mark {
   y: number;
 }
 
-/** The display list: every page of the document, laid out. */
-export interface Layout {
+/**
+ * The [paper](../../../CONTEXT.md#paper) a report is drawn on, in points: one
+ * width and one height for a whole render. The page box is fixed once the
+ * render opens, so this is the list's and a page carries none of its own (ADR
+ * 0069) — a consumer sizing a page reads it here.
+ */
+export interface Paper {
   width: number;
   height: number;
-  pages: Page[];
+}
+
+/** The display list: every page of the document, laid out, on one `Paper`. */
+export interface Layout extends Paper {
+  /** Every page, and never none: the band flow opens the body's first page
+   * whether or not anything renders on it. Typed as a non-empty tuple so a
+   * consumer reading `pages[0]` needs no check for a list that cannot exist. */
+  pages: [Page, ...Page[]];
   /** The group tree, in document order — the PDF target's bookmarks. */
   marks: Mark[];
 }
@@ -206,11 +219,17 @@ export const PX_PER_POINT: number;
  * order. `scale` is device pixels per point. `fonts` is the same record
  * given to `layout()`, so a TrueType family draws in its own face.
  *
+ * **Size the canvas to the page first** — `Layout.width` and `Layout.height`
+ * times `scale`, the paper every page of the list is drawn on. The ops are in
+ * the page's own coordinates, so a canvas short of that clips them, and the
+ * white is filled over the whole canvas rather than over a rectangle a page
+ * carries (ADR 0069).
+ *
  * It awaits its faces and images before it draws, and it draws whatever
- * happened in between: a canvas re-sized under a call still in flight is
- * filled at that call's own `scale`, not the size it now has. A caller that
- * repaints one canvas at changing scales owns that, by not letting a
- * superseded call reach a canvas still on screen.
+ * happened in between: a canvas re-sized under a call still in flight has its
+ * ops placed at that call's own `scale` on a canvas of the size it now has. A
+ * caller that repaints one canvas at changing scales owns that, by not letting
+ * a superseded call reach a canvas still on screen.
  */
 export function paint(
   ctx: CanvasRenderingContext2D,
@@ -232,3 +251,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

@@ -29,6 +29,7 @@ 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.