@quario/layout 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,15 +1,114 @@
-# 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.4.0] - 2026-09-07
-
-### Added
+# @quario/layout
+
+## 0.6.0
+
+### Minor Changes
+
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
+
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
+
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+
+## 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.
@@ -17,31 +116,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+## 0.3.0
 
-### Added
+### 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
@@ -52,7 +144,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
@@ -60,15 +151,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
@@ -77,9 +164,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
@@ -87,21 +174,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
@@ -110,9 +192,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
@@ -127,9 +206,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
@@ -137,12 +216,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
@@ -151,7 +228,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.
 
@@ -170,13 +246,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
@@ -189,13 +261,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

@@ -2,8 +2,8 @@
 
 **The paged layout of a [quario](https://www.npmjs.com/package/quario) report, as a display
 list.** `layout(options)` is a render target whose output is pages of boxes, text runs, rules
-and images in points — the layout the PDF target writes and the viewer and editor paint on screen,
-so the preview breaks its pages exactly where the document does.
+and images in points. The PDF target writes that layout, and the viewer and editor paint it on
+screen, so the preview breaks its pages exactly where the document does.
 
 You install this package directly only to consume the list yourself. `@quario/pdf`, `@quario/viewer`
 and `@quario/editor` depend on it and run it for you.
@@ -38,11 +38,17 @@ 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
-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.
+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 paper, so a page does not
+carry its own size.
+
+A page carries:
+
+- its `{ number, total }`,
+- its ops: `rect`, `line`, `image`, and `text`. A `text` op holds the string to draw, the face it
+  uses, and, for a built-in family only, the per-character advances the measurer laid it out
+  with. An unlicensed render adds one `mark` op.
+- its `boxes`, one per schema node drawn, named by the node's path.
 
 ## Options
 
@@ -51,7 +57,7 @@ named by the node's path.
 | `page`  | `{ size: "A4" \| "letter" \| [w, h], margin }` points | A4, 54pt |
 | `fonts` | A font mapping: family name to TrueType bytes         | none     |
 
-They are the pdf target's own `page` and `fonts`: pass the same object to `layout()` and to
+They are the pdf target's own `page` and `fonts`. Pass the same object to `layout()` and to
 `pdf()` and the two agree, because the pdf target runs this layout and paints its list.
 
 ## Painting on a canvas
@@ -61,34 +67,43 @@ 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 —
-no `img-src` grant, no URLs. `hit` answers which schema node was drawn at a point: the smallest box
+`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 `paint` fills the
+white over the whole canvas. `paint` decodes images 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.
 
-Text is drawn in the face the document will use. A family you pass as `fonts` is registered as a
-`FontFace` from your own bytes, and its runs are drawn as the browser shapes them — the same
-shaping the PDF gets from the same file, so ligatures, joined scripts and accents look on screen
-the way they will on paper. Text in the built-in families is drawn character by character at the
-measured advances, because the typeface a browser has for Helvetica, Times or Courier only stands
-in for the one the PDF writes, and without the correction a line would drift as it ran.
+Text is drawn in the face the document will use. `paint` registers a family you pass as `fonts` as
+a `FontFace` from your own bytes, and the browser then shapes its runs. That is the same shaping
+the PDF gets from the same file, so ligatures, joined scripts and accents look on screen the way
+they will on paper. `paint` draws text in the built-in families character by character at the
+measured advances. The typeface a browser has for Helvetica, Times or Courier only stands in for
+the one the PDF writes, and without that correction a line would drift as it ran.
 
 Inside a single run of a family you supply, the preview is not promised to place glyphs exactly
-where the PDF does: both read a glyph's own advance and neither applies the font's GPOS
+where the PDF does. Both read a glyph's own advance and neither applies the font's GPOS
 positioning, so a browser may kern by a fraction more. Where a line breaks, how wide a column is,
 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
-`PX_PER_POINT * devicePixelRatio`. Any zoom is a factor on top of that.
+`PX_PER_POINT` is how big a point is on screen — 96 dpi over PostScript's 72. A surface that draws
+a page at 100% therefore 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
-unlicensed. See [LICENSE](https://getquario.com/license).
+quario is commercial software. Evaluation is free and fully featured, and quario marks its output
+as unlicensed. See [LICENSE](https://getquario.com/license).

package/lib/canvas.js

@@ -140,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;

package/lib/fonts.js

@@ -165,8 +165,8 @@ let useFontkit = async () => {
 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");
+    throw TypeError(path + ": expected { regular, bold?, italic?, boldItalic? }");
+  if (def.regular == null) throw TypeError(path + ".regular: required");
   return path;
 };
 
@@ -279,6 +279,10 @@ export async function loadFonts(custom) {
   return { families };
 }
 
+// An array is a `typeof "object"` whose families would be named 0, 1, 2.
+/** @type {(custom: any) => boolean} */
+let record = (custom) => typeof custom === "object" && !Array.isArray(custom);
+
 /**
  * Check the shape of a host's font mapping without loading a parser.
  *
@@ -295,7 +299,7 @@ export async function loadFonts(custom) {
  */
 export let checkFonts = (custom, at = "options.fonts") => {
   if (custom == null) return;
-  if (typeof custom !== "object") throw Error(at + ": expected a record of families");
+  if (!record(custom)) throw TypeError(at + ": expected a record of families");
   for (let [name, def] of Object.entries(custom)) asFamily(name, def, at);
 };
 

package/lib/index.d.ts

@@ -22,7 +22,11 @@ export interface LayoutFontFamily {
 /** 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. */
+/**
+ * Host controls, taken and validated at the factory call: an option this
+ * target does not understand, or one of the wrong type, throws a `TypeError`
+ * there rather than costing the host the option in silence.
+ */
 export interface LayoutOptions {
   page?: LayoutPage;
   /**
@@ -159,12 +163,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 +183,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 +223,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,

package/lib/index.js

@@ -20,7 +20,7 @@
  * driver dispatches to is the band flow's, next door in `layout.js`; this
  * file adds none. The package publishes `lib/` verbatim.
  */
-import { breathe, walk } from "quario";
+import { breathe, hostOptions, walk } from "quario";
 import { listing, stamp } from "./canvas.js";
 import { checkFonts, loadFonts } from "./fonts.js";
 import { flow, furniture } from "./layout.js";
@@ -58,6 +58,19 @@ let markPages = async (canvas, marking) => {
   await overPages(canvas, () => canvas.watermark(mark));
 };
 
+// This target's whole option contract, checked at the factory call: the key
+// sets, then the geometry and the font mapping's shape. The `page` key set
+// closes here rather than in `pageBox`, which the two surface elements also
+// call -- a host configures those by assigning DOM properties, and nothing can
+// refuse an unknown one (`docs/adr/0072`).
+/** @type {(options: any) => void} */
+let checkOptions = (options) => {
+  hostOptions(options, ["page", "fonts"], "options");
+  hostOptions(options?.page, ["size", "margin"], "options.page");
+  geometry(options?.page);
+  checkFonts(options?.fonts);
+};
+
 /**
  * The layout target:
  * `quario().report(schema).render(layout({ page }), data)` resolves the
@@ -70,8 +83,7 @@ let markPages = async (canvas, marking) => {
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function layout(options) {
-  geometry(options?.page);
-  checkFonts(options?.fonts);
+  checkOptions(options);
   let custom = options?.fonts;
   /** @type {(stream: any) => (data?: any) => Promise<Layout>} */
   let compile = (stream) => async (data) => {

package/lib/layout.js

@@ -21,7 +21,7 @@
  * document's bands claim before anything is placed, and where they are drawn
  * on each finished page once the count is known.
  */
-import { display, imageError, isReportBand, text } from "quario";
+import { display, isReportBand, text } from "quario";
 import { balance } from "./balance.js";
 /** `Measured` is the measured table's own type, and the flow passes one
  * through: the region buffer measures early and the replay hands it back.
@@ -35,7 +35,6 @@ import { balance } from "./balance.js";
 import { gridOf, measureTable, sum, tableOf } from "./measure.js";
 import { adopt, measuring } from "./canvas.js";
 import { frame } from "./page.js";
-import { intrinsic } from "./image.js";
 import { CELL_PAD, NO_PAD, WHOLE, insetOf, isWhole, paintBox, sliceInset, unbox } from "./box.js";
 import {
   BAND,
@@ -122,19 +121,22 @@ let unsliceable = (block) => Boolean(block.picture || block.parts);
 // 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.
+// An image pixel as a page point, at the conventional 96 dpi the schema names
+// for `fit: "natural"`. Deliberately not `PX_PER_POINT`, which is the same
+// number answering a different question -- how a point becomes a length on
+// screen, where a zoom is a factor on top of it. An image's resolution and a
+// viewer's scale share a convention today and are free to stop.
+let PER_PX = 72 / 96;
+
 /** @type {(event: any, avail: number) => Picture} */
 let pictureOf = (event, avail) => {
-  // 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;
+  // The event states the size in pixels; a page is measured in points. The
+  // conversion is the first step of the same calculation the rest of this
+  // function is, at the conventional 96 dpi the schema names, and there is no
+  // header to read: the engine read it once, for every target, and a file too
+  // short to state a size never reached a target at all (`docs/adr/0067`).
+  let w = event.width * PER_PX;
+  let h = event.height * PER_PX;
   let width = event.fit === "width" ? avail : Math.min(w, avail);
   return {
     bytes: event.bytes,
@@ -195,23 +197,24 @@ let shrink = (block, room) => {
   block.h = inner + block.inset.t + block.inset.b;
 };
 
-// Draw one block whole at the cursor. A picture's background fills the
-// image's own box rather than the width of the flow -- there is no line for
-// it to sit behind. Text is placed line by line as each is drawn; a picture
-// is one box, so where it sits in the width it was given is worked out once.
+// Draw one block whole at the cursor. The box is the width the block was
+// given, exactly as `drawLines` paints one: an image's background and border
+// span the content width, or the slot's share inside a split, and never the
+// picture's own width. `fit` sizes the picture and `align` places it in the
+// inner box; neither moves an edge. Text is placed line by line as each is
+// drawn; a picture is one box, so where it sits is worked out once.
 /** @type {(canvas: Canvas, block: Block, x: number, avail: number) => void} */
 let drawPicture = (canvas, block, x, avail) => {
   let inset = block.inset;
   let { bytes, format, w, h } = /** @type {Picture} */ (block.picture);
-  let outer = w + inset.l + inset.r;
-  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);
+  paintBox(canvas, x, canvas.y, avail, block.h, block.style, block.bg);
+  canvas.box(block.path, x, canvas.y, avail, block.h);
+  let inner = Math.max(avail - inset.l - inset.r, 1);
   canvas.picture(
     block.path,
     bytes,
     format,
-    at + inset.l,
+    x + inset.l + shift(block.align, inner - w),
     canvas.y - inset.t - block.drop - h,
     w,
     h,

package/lib/page.js

@@ -15,6 +15,7 @@
 
 // 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.
+// fallow-ignore-next-line code-duplication -- @quario/docx keeps a deliberate copy of these rules: a flow target runs no layout, and taking @quario/layout for a two-entry table would install the pagination engine with it. test/page-sizes.test.js holds the two in sync (ADR 0039).
 let SIZES = /** @type {Record<string, [number, number]>} */ ({
   A4: [595.28, 841.89],
   letter: [612, 792],
@@ -22,7 +23,7 @@ let SIZES = /** @type {Record<string, [number, number]>} */ ({
 
 /** @type {(msg: string) => never} */
 let err = (msg) => {
-  throw Error(msg);
+  throw TypeError(msg);
 };
 
 /** @type {(value: number) => boolean} */

package/lib/paint.js

@@ -235,18 +235,20 @@ let decode = async (page) => {
 /**
  * Paint one page of the list onto a Canvas 2D context: a white page, then
  * every op in order. `scale` is device pixels per point — the caller sized
- * the canvas, so it knows. `fonts` is the host's font mapping, the same
+ * the canvas, so it knows, and the canvas it sized is the page's own size,
+ * which is why the paper is filled over the whole store and no page geometry
+ * is asked for (ADR 0069). `fonts` is the host's font mapping, the same
  * record given to `layout()`, so a TrueType family draws in its own face.
  *
  * 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 — which is what the viewer's
- * stage retires a page for (docs/adr/0046).
+ * 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 store 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 — 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
+ * drawn around it.** The engine vouched for the magic numbers and
  * 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
@@ -263,9 +265,16 @@ export async function paint(ctx, page, { scale = 1, fonts } = {}) {
   await loadFaces(fonts);
   let bitmaps = await decode(page);
   ctx.save();
-  ctx.setTransform(scale, 0, 0, scale, 0, 0);
+  // The paper, over the whole store rather than over the page's own box: a
+  // page carries no geometry to fill to (ADR 0069), and the caller has already
+  // sized the canvas to the page — the obligation the ops themselves put on it,
+  // since a short store clips them. In device pixels, before the scale goes on,
+  // so a store rounded up to a whole pixel is covered to its edge rather than
+  // left a sliver of whatever it held.
+  ctx.resetTransform();
   ctx.fillStyle = "#fff";
-  ctx.fillRect(0, 0, page.width, page.height);
+  ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+  ctx.setTransform(scale, 0, 0, scale, 0, 0);
   for (let op of page.ops) paintOp(ctx, op, bitmaps);
   ctx.restore();
 }

package/lib/style.js

@@ -54,6 +54,7 @@ let vshift = (valign, extra) => (Object.hasOwn(VSHIFT, valign) ? VSHIFT[valign]
 
 // A declared colour as a `Color`, or null when the value is not one.
 /** @type {(value: any) => Color | null} */
+// fallow-ignore-next-line code-duplication -- each target reads a declared hex into its own type; neither may import a sibling, and the engine's stream is all they share
 let col = (value) => {
   let match = typeof value === "string" && HEX.exec(value);
   if (!match) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/layout",
-  "version": "0.4.0",
+  "version": "0.6.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.7.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.7.0"
+    "quario": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {

package/lib/image.js

@@ -1,58 +0,0 @@
-/**
- * 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("could not read the image's size from its bytes");
-  return { w: w * PER_PX, h: h * PER_PX };
-};