quario 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,15 +1,105 @@
-# Changelog
-
-All notable changes to quario 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.7.0] - 2026-09-07
-
-### Added
+# quario
+
+## 0.9.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
+
+- The engine verifies a license key against a new signing key.
+
+## 0.8.0
+
+### Minor Changes
+
+- **BREAKING: an image whose header does not state its size now fails on every
+  target.** A PNG or JPEG truncated before its dimensions used to render on the
+  HTML and CSV targets — the browser coped, and CSV has no picture to place —
+  while failing on the PDF and XLSX targets, which have to know how big a
+  picture is before they can put it anywhere. One file, two verdicts, depending
+  on where the report was sent.
+
+  It is now a single render error, raised where every other verdict on image
+  bytes is raised and naming the item's `source` the same way — for example
+  `header[0].source [=$.input.logo]: could not read the image's size from its bytes`.
+  A report that renders as a PDF today is unaffected: those bytes already
+  failed there. What changes is a report that renders as HTML today on bytes no other target
+  would accept: it now fails, and the file it names is one no target could ever
+  have drawn correctly.
+
+  Nothing further has changed about what the engine promises: a file whose size
+  reads but whose pixel data is corrupt is still nobody's guarantee, and each
+  target does whatever its own machinery does with it.
+
+- **The image event carries the picture's size.** `width` and `height`, in
+  pixels, read from the same header the format is sniffed from. A target — the
+  built-in ones, or your own — places a picture from two fields instead of
+  parsing a PNG's IHDR and a JPEG's frame header for itself.
+- **A page-number token says which page value it is.** A value token whose
+  interpolation is exactly `{{ page.number }}` or `{{ page.total }}` now carries
+  `field` on the event stream, holding that same string. The `value` is
+  unchanged — the number the page band was called with — so nothing renders
+  differently; `field` tells a target whose own document format numbers pages
+  that it may write its own live field there instead of the number this render
+  saw. Anything computed from them (`{{ page.number + 1 }}`, `{{ pad(page.total)
+}}`) is an ordinary value and carries no `field`, so write the bare token
+  wherever a live number matters.
+
+### Patch Changes
+
+- **A PNG wider or taller than 65535 pixels is no longer misplaced.** Its
+  dimensions were read from the low half of each of IHDR's four-byte fields, so
+  a 70000-pixel panorama measured 4464 pixels and was laid out at that size,
+  confidently and silently.
+- **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.
+
+## 0.7.0
+
+### Minor Changes
 
 - **Styled runs.** Bold a word, colour a phrase, or format one value inside a
   sentence, and have it survive into the PDF and the spreadsheet — not only the
@@ -47,8 +137,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   seen in the definition alone, without data, so a quiet `warnings` list is not
   a promise that every declaration will be read.
 
-### Changed
-
 - **A `format` declaration now needs one value to speak about, and a cell can
   give it one.** Previously a `format` on a cell reached every interpolation in
   it and skipped the literal text between them, which meant
@@ -78,8 +166,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   twice. `plan()` reports the cells this affects wherever it can see them
   without data.
 
-### Fixed
-
 - **`round`, `floor` and `ceil` reuse their formatters instead of rebuilding
   one per call.** The three reach the decimal you wrote through `Intl`, and
   each call built a fresh formatter to do it — so a detail column of
@@ -88,7 +174,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Every answer is the value it was before: the rounding mode and the digit
   count are both part of what a reused formatter is found by, so no call can
   be handed one built for another.
-
 - **`round`, `floor` and `ceil` name themselves when they refuse an `n`.** All
   three threw `n must be a number from 0 to 100`, so a cell calling more than
   one was told how it failed and never which call; the message now opens with
@@ -112,7 +197,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the same and are not diagnostics, so a host following that example rethrew
   report faults as its own. Nothing about the guard changes; it never behaved
   the way the page described.
-
 - **A misused inline reducer says what it is, instead of how it folds.**
   `{{ min(1, 2) }}` — the two-argument scalar `min` quario does not have —
   failed at the cell with `(rows || []).map is not a function`, the fold's own
@@ -130,9 +214,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   mistake: `sum(@.lines)` on a row carrying no lines is `0`, exactly as an
   empty array gives.
 
-## [0.6.0] - 2026-09-07
+## 0.6.0
 
-### Added
+### Minor Changes
 
 - **`imageError(path, said, cause)`**, the mint a render target raises an image
   failure through. The engine vouches for an image's magic numbers and no
@@ -141,7 +225,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   that asked for the bytes and keeps the failing class and message behind it,
   so one report reads the same however it is rendered. It is not a diagnostic:
   `isDiagnostic` does not answer for one.
-
 - **Formatted cells render dramatically faster.** The engine built a fresh
   `Intl` formatter for every presented cell and now keeps them, keyed on
   everything a formatter is built from — the kind, the locale, the digit count,
@@ -197,14 +280,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`sort` is stable**: rows whose keys compare equal keep the order they
   arrived in. The engine has always sorted this way; the promise is new.
-
 - `currencyOf(style, options)` joins the package's exports beside `format()`.
   It answers which currency code a cell wears — its own when it declares one,
   else the instance default — for a target that needs the code itself rather
   than presented text. A cell that declared a code the engine could not accept
   carries `style.currency` as `null`, so `style.currency ?? yourDefault` is the
   wrong spelling and this helper is the right one.
-
 - **A cell may name its own currency.** `currency` is a new style declaration
   beside `format` — a three-letter ISO 4217 code saying what a money cell is
   denominated in.
@@ -257,14 +338,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `split-start` events carry `path`, the split definition's schema path, as
   `item` and `image` events already do. A consumer can now name the definition
   behind a split without tracking position.
-
 - `fractionDigits(kind, options)` is exported beside `format()`: how many
   fraction digits a kind presents, or nothing for a kind that carries no
   count. It is the table the official targets read, and it is public so a
   consumer writing its own target presents the same digits they do.
-
-### Changed
-
 - **A `date` cell with no `form` now presents `medium`, not the runtime's own
   default.** A `date` that names no form used to render whatever the platform's
   default date format was — under `en-US`, `8/14/2026` — which matched none of
@@ -285,18 +362,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   to write no number format. Read `style.format.kind` where you read
   `style.format`, and take the digit count off the declaration rather than
   computing one.
-
 - **`fractionDigits` takes the whole style.** Its first argument was the kind
   and is now the style, matching `format()` and `currencyOf()`.
   `fractionDigits("number")` becomes
   `fractionDigits({ format: "number" })`. Targets no longer need it at all —
   the count rides on the declaration the stream carries.
-
 - **`typed()`'s second argument is the resolved declaration.** Pass
   `style.format` as it arrives on the stream; it reads the kind from the
   object. The shorthand string is still accepted, and omitting the argument is
   unchanged.
-
 - **A rejected box value is now dropped from the resolved style rather than
   carried on it.** A `border*` or `padding*` declaration written as an `=`
   expression used to cross the render stream with whatever the expression
@@ -435,23 +509,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A `currency` code that is not a readable currency now presents nothing in
   every target, rather than the worksheet inventing a number format from it
   while the other targets fell back to the unformatted value.
-
-### Fixed
-
 - **A split slot is typed with the declarations the traversal accepts.**
   `SplitSlot` reused the band items' style types, so TypeScript refused
   `valign` on an image slot — legal there, and only there — and admitted
   `spaceBefore`/`spaceAfter` on a slot, which the engine rejects. Two new
   exported types, `SlotStyleDeclarations` and `SlotImageStyleDeclarations`,
   now say what a slot may declare.
-
 - **A page band closure is typed as what it returns.** `PageBandRenderers`
   declared `header`/`footer` as returning item and image events only, while a
   split in a page band has always come back as its bracket — `split-start`,
   one event per slot, `split-end`. The closures now return `PageBandEvent[]`,
   a new exported union naming all four, so a TypeScript host reading a page
   band no longer types `role` onto a `split-end` that carries none.
-
 - **A computed style value the schema does not accept now leaves the layer
   below in place**, which is what the schema has always said it does —
   "contributes nothing, same as omit". The name is dropped from the resolved
@@ -486,7 +555,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the cell falls back to display text, as the documented rule says any
   unrecognised kind does. Before, such a cell could render `[object Undefined]`.
   A literal was never affected: it is checked against the four kinds.
-
 - **A pinned report header now refuses a lead on every band that can sit under
   its box, and only where the document settles which one that is.** When
   `header` declares a `height`, an authored `spaceBefore` on the first item of
@@ -516,9 +584,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   than reporting against the report header, which is a band this rule never
   covers.
 
-## [0.5.0] - 2026-09-05
+## 0.5.0
 
-### Added
+### Minor Changes
 
 - **`STYLE_NAMES`**, every name in the style vocabulary as a read-only list,
   in the order the specification's table lists them. A tool that offers the
@@ -540,9 +608,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   on a band image, whose boxes have no such slack. A row's or a split's layers
   under its cells' or slots' own. Undeclared is not a declaration: each target
   keeps its own default.
-
-### Changed
-
 - **A table row's `style` now resolves onto that row's cells**, the box
   included, instead of meaning something different on every output. Before,
   padding and border on `detail.header`, `detail.row` or a total row's `style`
@@ -565,9 +630,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   carries only what layers by ordinary means, and a row whose whole block was
   box carries no `style` at all.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Changed
+### Minor Changes
 
 - **`format: "date"` now reads a date string, not only a `Date`.** A JSON
   document has no date type, so the kind could not be reached from parsed
@@ -591,9 +656,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`typed(tokens, kind?)` takes the cell's `format` kind.** Passing `"date"`
   opts into the same revival, for consumers that write typed cells. The
   one-argument call is unchanged.
-
-### Fixed
-
 - **The TypeScript declarations accept the box.** The per-side `padding*` and
   `border*` names, and the table's `detail.header`, were validated by the
   engine from 0.3.0 but were missing from the shipped declarations, so a
@@ -608,9 +670,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   about rendering changes: a report that compiled through a cast produces the
   same output without one.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Added
+### Minor Changes
 
 - **`format` is a closed style name.** `number` / `currency` / `percent` /
   `date` on text items, column cells, headers, and totals. Not images, not
@@ -618,19 +680,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   live on `quario({ locale, currency, timeZone })`. The public `format()`
   helper is how targets present a kind; a kind on the wrong type contributes
   nothing.
-
 - **The report header may pin a `height` from the page top.** Dual-shaped
   like `detail`: an item array, or `{ height, items }`. `page.margin` is a
   document field (one number, all four sides), required with `height` and
   legal without. Authored `spaceBefore` on the first occupying item of the
   next band is refused.
-
 - **`spaceBefore` / `spaceAfter` return as item flow spacing.** Blank space
   before or after a band item, in points, including band images and splits as
   band items. Adjacent gaps add. Table cells, `row.style`, headers, totals,
   and split slots refuse the names. `spaceBefore` drops at a fresh body page
   or strip top; page-band items keep it. Leading and inset stay cut.
-
 - **Per-side padding and border on the closed style vocabulary.**
   `paddingTop` / `Right` / `Bottom` / `Left` (points, ≥ 0) and, per side,
   `border*Width`, `border*Style` (`solid` | `dashed` | `dotted`),
@@ -640,18 +699,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   than a solid black stroke. The names are legal wherever `background` is,
   including images, plus `row.style`. The report default still takes only
   `family` and `size`. Column `%` widths are border-box.
-
 - **`detail.header` is the header-row box.** `{ style }` only, a different
   path from `columns[i].header`. It crosses the seam as `table-start.style`.
-
-### Changed
-
 - **A table total is N rows.** Before, `total` was one row: a flat cell
   array or `{ style, cells }`. After, it is absent or a non-empty array of
   `{ cells, style?, visible? }`. A one-row total is `[{ cells: [...] }]`.
   `total: []` is a definition error. Paths are `detail.total[r].cells[i]`.
   The stream yields one `total-row` per emitted row.
-
 - **A visible text item occupies a line at its own `size`.** Empty display
   used to take the report default's leading in PDF and collapse in HTML;
   `"a\n\nb"` broke in PDF and collapsed to a space in HTML. A visible item
@@ -660,9 +714,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   table cells stay contentless for height. This is not a spacing primitive;
   `visible: false` is still how an item leaves the layout.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **A report default: one `style` block for the whole document.** A top-level
   `style` beside `header`/`detail`/`footer` states the typeface a report is set
@@ -672,21 +726,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a text declaration on an image item is. Values are literals or `=`
   expressions like any other style block's, resolved once per render in report
   scope.
-
 - **`report-start` carries the resolved report default as `style`.** A
   report-level fact, never merged into an item's own `style`: an event's
   `style` stays what the author wrote on that node, and a consumer composes the
   default itself, once — under its own band-role defaults and under every
   event's own style. Absent when the report declares none, so a consumer
   written before this field renders in its own baseline exactly as it did.
-
 - **An `uppercase` style declaration.** A boolean beside `bold` and `italic`,
   literal or an `=` expression, for the capitalised column labels business
   forms are usually set with. It is capitals, not small caps — real small caps
   need a font feature the PDF target's built-in faces cannot supply, so the
   declaration promises only what every target can draw. Image items keep
   refusing it, as they refuse every text declaration.
-
 - **A `split` item places values across the line instead of down the band.**
   The invoice header's "seller left, customer right", which a band could not
   say before. `{ "type": "split", "slots": [...] }` takes two or more slots,
@@ -697,13 +748,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a slot that renders nothing keeps its width, so a line's geometry never
   moves with the data. Splits may appear in every item array except table and
   total cells.
-
 - **`split-start` / `split-end` bracket a split's slots on the event stream.**
   `split-start` carries the slot geometry, then one ordinary `item` or `image`
   event per slot in order, then `split-end`. Existing consumers need no
   change: the walk driver's missing-handler rule means a target that ignores
   the bracket still receives the slot items and renders them stacked.
-
 - **`quario().plan(schema, funcs?)` hands the whole traversal over at once.**
   Returns `{ report, problems, anchors }` from one descent: the compiled
   report (`null` while the document has problems), every problem as
@@ -727,12 +776,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   display rule behind the token join, re-exported beside `text()` so a stream
   consumer that stringifies token values itself renders exactly what the
   official targets render — Dates included.
-
 - **`maxDepth: Infinity` opts a query budget out.** The data query's traversal
   budgets accept an explicit `Infinity` per key for "this budget, unbounded".
   The 500-deep default is unchanged — it is now padvinder's own, applied for
   every consumer rather than added by quario at the seam.
-
 - **Located data-query errors carry padvinder's code and span.** A `data`
   query that does not parse now surfaces with padvinder's `code` and
   `start`/`end` offsets into the query you wrote — filter faults included —
@@ -742,23 +789,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `PADVINDER_UNKNOWN_FUNCTION`, or `PADVINDER_SYNTAX` for a path character or
   filter body that is open-endedly not a query. Traversal budgets exceeded at
   render time keep `limit`/`actual` and carry no span.
-
-### Changed
-
 - **Cells render straight over the engine scope chain.** A text cell no longer
   allocates a wrapper scope and an anchor pair per cell per row — quario's
   chain already binds `$` at the render base and `@` on the detail row, and
   sjabloon now renders over it as-is. A 4-column stream over a million rows
   went from 1.7s to 0.5s. No report changes what it renders. Requires
   sjabloon 0.11.
-
 - **A compiled report's `functions` carry signatures.** Each entry is now
   `{ name, arity, doc? }` instead of a bare name — `arity` from the function's
   declared parameter count (or its own numeric `arity` where rest parameters
   mislead `length`), `doc` from an own `doc` string when it carries one — in
   the same call-first-seen order. `names` is unchanged. Requires xprsn 0.11
   and sjabloon 0.11.
-
 - **A bare `Date` renders as ISO 8601 UTC, the same on every machine.**
   Display text for a `Date` value was `String(date)`, which bakes the
   rendering host's timezone and locale into the output — so one report
@@ -767,7 +809,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   rule; an invalid `Date` keeps its deterministic `Invalid Date` text.
   Reports that want a formatted date keep using a registered function,
   exactly as before.
-
 - **A bad literal pattern in the data query is a definition error.** A typo'd
   I-Regexp written as a string literal in `match()`/`search()` used to
   produce a plausible empty report with no signal; `report()` and
@@ -779,7 +820,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   fault in an expression: the engine that decided the fault names it. A
   pattern that arrives from render data keeps RFC 9535 semantics and still
   matches nothing at render time. Requires padvinder 0.8.
-
 - **Each engine relocates its own diagnostic.** A located error is now a copy
   made by the engine that raised it (xprsn, sjabloon, or padvinder), so it
   carries every field that engine puts on a diagnostic — nothing is lost in
@@ -787,9 +827,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   passes that engine's own `isDiagnostic`. Host errors are wrapped as plain
   errors with no diagnostic metadata, exactly as before. Requires xprsn 0.10,
   sjabloon 0.9, and padvinder 0.5. No report changes what it renders.
-
-### Fixed
-
 - **A host error cannot pose as the report's diagnostic.** `report()` rethrows
   the first definition problem's located engine error; it chose that error by
   probing for a `code` property, so a host error class that stamps `code` on
@@ -798,9 +835,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `isDiagnostic`; everything else falls back to a plain `SyntaxError` naming
   the first problem, as before.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **A compile-once report engine.** You hand it a JSON report definition and
   data; it plans once and streams render events that every target consumes.

package/README.md

@@ -63,7 +63,7 @@ Compiles a report and returns the compiled report. `stream(data)` is the raw eve
 (e.g. `html()` from `@quario/html`) or your own.
 
 A render is async: quario awaits key verification before the target sees its first event. A
-malformed target throws synchronously from `render`, before the first event; definition problems
+malformed target throws synchronously from `render`, before the first event. Definition problems
 throw earlier, at `report()`.
 
 The data pre-pass (select, filter, sort, aggregate) runs when you call the renderer, because a
@@ -80,7 +80,7 @@ report.paths; // padvinder's deeply frozen dependency topology for the `data` qu
 
 Events arrive in render order: `report-start`, report `header` items, then either the `empty`
 items or the group/detail walk, then `footer` items, `report-end`. Group instances bracket their
-content with `group-start`/`group-end`; a table detail yields `table-start`, one `row` per visible
+content with `group-start`/`group-end`. A table detail yields `table-start`, one `row` per visible
 row, one `total-row` per emitted total row, and `table-end`.
 
 | Event          | Carries                                                                                                                                                                                                             |
@@ -88,7 +88,7 @@ row, one `total-row` per emitted total row, and `table-end`.
 | `report-start` | `params`, resolved report `aggregates`, optional `page` band closures, `columns`, `style` (the report default), `marking`, `margin`, `headerHeight`, and the instance's `locale` / `currency` / `timeZone` when set |
 | `item`         | `role`, `path`, `tokens`, optional `style`, `run`                                                                                                                                                                   |
 | `image`        | `role`, `path`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`                                                                                                                          |
-| `split-start`  | `role`, `slots` (each an optional `width`), optional `style`; one `item` or `image` per slot follows, then `split-end`                                                                                              |
+| `split-start`  | `role`, `slots` (each an optional `width`), optional `style`. One `item` or `image` per slot follows, then `split-end`                                                                                              |
 | `split-end`    | -                                                                                                                                                                                                                   |
 | `group-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `reset`, `columns`                                                                                                                                  |
 | `group-end`    | `name`, `depth`                                                                                                                                                                                                     |
@@ -98,19 +98,28 @@ row, one `total-row` per emitted total row, and `table-end`.
 | `table-end`    | -                                                                                                                                                                                                                   |
 | `report-end`   | -                                                                                                                                                                                                                   |
 
+The full field semantics are in the [event stream reference](https://getquario.com/docs/reference/events/).
+
 **Cells carry tokens.** A cell is `{ tokens, style? }`. Each token is either `{ literal }`
 (static template text, verbatim) or `{ value }` (one interpolation's _pre-format_ value, the
 expression result before any stringification). This is the typed seam: a cell whose template is `{{ @.amount }}` holds one value token with the
 number itself, so a spreadsheet consumer writes a real numeric cell. `Total: {{ @.amount }}` mixes
 a literal and a value, so the cell is text only.
 
+**A page-number token names itself.** A value token whose interpolation is exactly
+`{{ page.number }}` or `{{ page.total }}` also carries `field`, holding that same string. The
+value is the number the render used for this page. `field` says which page value the token stands
+for, so a target whose own document format numbers pages can write its own live field there
+instead. Anything computed from them carries no `field`.
+
 **Escaping is the consumer's job.** A target that embeds values in markup must escape them at its
 own edge.
 
-**`report-start.marking`** carries the evaluation wording when the render is unlicensed, or while
-verification is still settling. Licensed streams omit it. Targets place the marking; they do not
+**`report-start.marking`** carries the evaluation wording when no license covers the render, or while
+verification is still settling. Licensed streams omit it. Targets place the marking. They do not
 author its wording. **`columns`** on `report-start` / `group-start` is the declared
-page column count when present. `@quario/pdf` and `@quario/html` lay page columns out;
+[page column](https://getquario.com/docs/diving-deeper/bands/#flowing-in-columns) count when
+present. `@quario/pdf` and `@quario/html` lay page columns out.
 xlsx never will.
 
 ### `text(tokens)`
@@ -124,7 +133,7 @@ Exactly one value token holding a finite number, a boolean, or a valid `Date` ke
 pre-stringify value. Anything else, including a lone null, reports `undefined` and joins to
 display text. Passing the cell's resolved `format` kind opts into the seam's one coercion: under
 `"date"`, an RFC 3339 string revives to the `Date` it names. Spreadsheet consumers use this for
-real numeric cells;
+real numeric cells.
 [`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
 
 ### `styledRuns(tokens)`
@@ -138,12 +147,12 @@ target cannot drift from them.
 ### `walk(events, handlers)` / `breathe()`
 
 `walk` is the delivery driver every official target uses. Pass one render's event iterable and
-per-event handlers keyed by type; a missing handler ignores that event. It pulls on demand, hands
-the loop back between batches, and delivers the opening event before pulling a second, so a
+per-event handlers keyed by type. A missing handler ignores that event. It pulls on demand,
+returns the loop between batches, and delivers the opening event before pulling a second, so a
 target can settle `report-start` (page bands, marking) there instead of draining the stream
 itself.
 
-`breathe()` is that hand-back alone. Await it between batches of a loop you own; `walk` already
+`breathe()` is that return alone. Await it between batches of a loop you own. `walk` already
 calls it for you.
 
 ### Presentation helpers
@@ -154,11 +163,11 @@ cell the same way:
 - `display(value)` — the scalar rule `text()` joins with: a `Date` as ISO 8601 UTC, nullish as
   the empty string, everything else `String(value)`.
 - `format(value, style?, options?)` — presents a token under the cell's resolved `format`
-  declaration (its kind and modifier, and for `currency` the cell's own code); `undefined` when the kind does not apply, so the caller falls back to
-  `display()`.
+  declaration (its kind and modifier, and for `currency` the cell's own code). It answers
+  `undefined` when the kind does not apply, so the caller falls back to `display()`.
 - `fractionDigits(style?, options?)` — the digit count a resolved `format` declaration presents:
   the kind's own (two for `number` and `percent`, a currency's minor units for `currency`) unless
-  the declaration's `digits` overrides it; `undefined` where there is no count.
+  the declaration's `digits` overrides it. It answers `undefined` where there is no count.
 - `currencyOf(style?, options?)` — which code a money cell wears: its own, else the instance's.
 - `isReportBand(role)` — whether a role names one of the report's own bands rather than a
   group's.
@@ -167,8 +176,8 @@ cell the same way:
 
 ### `validate(schema, functions?)`
 
-Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
-empty array means valid.
+Validates a definition without rendering it. It returns every problem as a path-prefixed string.
+An empty array means valid.
 
 ```js
 validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
@@ -193,7 +202,7 @@ is not a problem at a lower severity, which is why it has no `diagnostic` — no
 engine decided. Neither warning below locates into an authored source, so none carries a `source`
 today. **A warning is never fatal**: a document carrying only warnings compiles and
 renders, so `report` is `null` on `problems` alone. Two declarations warn today — a `currency` on
-a cell whose `format` is not `"currency"`, and a table where every column is sized and the widths
+a cell whose `format` is not `"currency"`, and a table where the author sized every column and the widths
 total under 100 — and the list is advisory and deliberately incomplete, so a quiet one is not a
 promise that every declaration will be read. `validate()` returns problems only.
 
@@ -208,10 +217,10 @@ else console.error(problems[0].path, problems[0].message);
 
 True when a caught value is a **located diagnostic**: an error xprsn, sjabloon or padvinder
 minted — thrown by that engine, or re-thrown by quario with the engine original behind it.
-Authentication checks identity. An error that only matches the shape does not pass.
+Authentication tests identity. An error that only matches the shape does not pass.
 
-Being located is not what the guard reads: quario's own verdicts on a document and a registered
-function's own throw are located too, and neither is a diagnostic. Errors a report throws
+Location is not what the guard reads: quario's own verdicts on a document and a registered
+function's own throw carry a location too, and neither is a diagnostic. Errors a report throws
 name the path they failed at — and the offending source, where there is one — while keeping their
 original type (`SyntaxError`, `TypeError`, `RangeError`). What a diagnostic adds on top is
 metadata an engine vouches for: `code`, `start`/`end` offsets, and, for a query budget in place
@@ -237,7 +246,7 @@ try {
 | `run.<name>`  | Running accumulator values on the current detail row                |
 
 Each anchor is a distinct object. Absent reads are `null`, so `x == null` holds for a missing
-field; reading _through_ a null base still throws, so use `?.`.
+field. Reading _through_ a null base still throws, so use `?.`.
 
 ## Options
 
@@ -245,18 +254,19 @@ field; reading _through_ a null base still throws, so use `?.`.
 quario({ query: { maxNodes: 10_000, maxDepth: 64, maxResults: 1_000 } }).report(schema, functions);
 ```
 
-`query` bounds the JSONPath data selection. Hosts set budgets through this API argument;
-definitions do not carry it. Failures are located at `data`, keep their `RangeError` type, and
+`query` bounds the JSONPath data selection. Hosts set budgets through this API argument.
+Definitions do not carry it. Failures point at `data`, keep their `RangeError` type, and
 carry `code`, `limit`, and `actual`. Every render starts with fresh counters.
 
 ## Writing a render target
 
 Read the stream through the public API. Do not reach for engine internals. A complete, tested
 Markdown target lives in the repository at `example/markdown.js` in about 70 lines. The built-in
-targets are written against the same public API.
+targets use the same public API.
 
 Two rules a target owes its users: escape or neutralize every `value` token at your own edge, and
-map the style vocabulary to your own formatting model rather than expecting CSS.
+map the [style vocabulary](https://getquario.com/docs/reference/style-declarations/) to your own
+formatting model rather than expecting CSS.
 
 The stream is additive. The walk driver skips any event you register no handler for, so a target
 that ignores a newer event (for example, `example/markdown.js` has none for `image`) keeps rendering
@@ -272,12 +282,19 @@ package, so it runs under a script policy that omits `unsafe-eval`. The test sui
 under Node's `--disallow-code-generation-from-strings` flag, a source scan, and a Playwright
 harness that loads the published files under a strict CSP.
 
+## 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
+the [engine reference](https://getquario.com/docs/reference/quario/) is this package's own API.
+
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key in the options; it is verified offline:
+Pass your license key in the options. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/host.js

@@ -0,0 +1,89 @@
+/**
+ * What a host got wrong in a target factory's options, named. A target
+ * refuses what it does not understand at the factory call, so a typo costs
+ * one stack trace at the line the host wrote rather than a wrong document
+ * nothing reports (`docs/adr/0072`).
+ *
+ * Here rather than in a target for the reason `imageError` carries beside it:
+ * every target needs it, no two of them may depend on each other, and the
+ * engine is what they all already have. Nothing an author writes reaches this
+ * module -- these are host API, and no located diagnostic is involved.
+ */
+
+/** @type {(msg: string) => never} */
+let fail = (msg) => {
+  throw TypeError(msg);
+};
+
+/**
+ * An object a host may have written by hand: not an array, not a function, and
+ * not `null`, each of which is a different mistake wearing `typeof "object"`.
+ *
+ * @type {(value: unknown) => boolean}
+ */
+let plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// Own keys only: an inherited enumerable property is the prototype's business,
+// and naming it back at the host would name something they never wrote.
+/** @type {(value: object, keys: readonly string[], at: string) => void} */
+let closed = (value, keys, at) => {
+  for (let key of Object.keys(value))
+    if (!keys.includes(key)) fail(at + ': unknown option "' + key + '"');
+};
+
+/**
+ * A target's own options, with its key set closed. Nullish is absence, which
+ * is what the engine does with every value a host omits, so a host writing
+ * `meta: config.meta ?? null` is not a host making a mistake.
+ *
+ * @template T
+ * @param {T} value The options object, or a nested one.
+ * @param {readonly string[]} keys Every key this object may carry.
+ * @param {string} at The option path, which prefixes the failure.
+ * @returns {T} `value`, unchanged.
+ */
+export let hostOptions = (value, keys, at) => {
+  if (value == null) return value;
+  if (!plain(value)) fail(at + ": expected an object");
+  closed(value, keys, at);
+  return value;
+};
+
+/** The three document properties a host may write. */
+let PROPERTIES = ["title", "author", "subject"];
+
+// Nullish is absence here too, one level down: a host writing
+// `{ title: config.title }` over a config that carries no title has made no
+// mistake, and a target skips the property the same way it skips a key that
+// was never written.
+/** @type {(value: any, at: string) => void} */
+let everyString = (value, at) => {
+  for (let key of Object.keys(value))
+    if (value[key] != null && typeof value[key] !== "string")
+      fail(at + "." + key + ": expected a string");
+};
+
+/**
+ * The `meta` option every document target takes, validated whole: those three
+ * properties, each a string, and never a date. What a host cannot write is
+ * what keeps a render reproducible -- each of these formats has one part with
+ * a slot for a clock, and none of them has a way to fill it.
+ *
+ * The contract is one thing, so it is checked in one place. What stays a
+ * target's own is the name each property carries in its format.
+ *
+ * Returns a **copy**, so the properties are read once, here. A host that
+ * mutates its options object between renders cannot make one configured
+ * target write two different documents, and no target has to remember to
+ * copy for itself.
+ *
+ * @param {any} value The `meta` option.
+ * @param {string} at The option path, which prefixes the failure.
+ * @returns {any} A copy of `value`, or undefined when the host wrote none.
+ */
+export let hostMeta = (value, at) => {
+  hostOptions(value, PROPERTIES, at);
+  if (value == null) return undefined;
+  everyString(value, at);
+  return { ...value };
+};

package/lib/image.js

@@ -0,0 +1,92 @@
+/**
+ * What the engine reads out of an image item's bytes: which format they are,
+ * and how big the picture is. Read, never decoded -- a magic number, a PNG's
+ * IHDR and a JPEG's frame header, and nothing here looks at a pixel.
+ *
+ * Both answers ride on the image event, so no target reads these headers
+ * again. That is the whole of `docs/adr/0067`: two targets used to keep a
+ * parser each, in different units and with the same bug, and the engine was
+ * already in these bytes to name the format.
+ */
+
+// The two raster formats an image item may carry, as the bytes announce
+// themselves: PNG's 8-byte signature and JPEG's start-of-image marker. Read,
+// never decoded -- the engine answers which format the bytes are, not what
+// they depict.
+let PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+let JPEG = [0xff, 0xd8, 0xff];
+
+/**
+ * The image seam: name the format a `source` expression's bytes hold, or null
+ * when they are not image bytes at all -- including when they are not bytes.
+ * The traversal sniffs once per image event and the answer rides on the event,
+ * so no consumer repeats it.
+ *
+ * @param {any} bytes The value a `source` expression yielded.
+ * @returns {"png" | "jpeg" | null} The format, or null when unreadable.
+ */
+export function sniff(bytes) {
+  if (!(bytes instanceof Uint8Array)) return null;
+  if (PNG.every((byte, i) => bytes[i] === byte)) return "png";
+  if (JPEG.every((byte, i) => bytes[i] === byte)) return "jpeg";
+  return null;
+}
+
+/** @type {(bytes: Uint8Array, at: number) => number} */
+let word = (bytes, at) => (bytes[at] << 8) | bytes[at + 1];
+
+// A PNG states each dimension in four bytes, so two words make one number.
+/** @type {(bytes: Uint8Array, at: number) => number} */
+let long = (bytes, at) => word(bytes, at) * 0x10000 + word(bytes, at + 2);
+
+// The three codes in C0..CF that are not frame headers: DHT, the JPG
+// extension, and DAC. Named as a set so the frame test is one range and one
+// lookup rather than a chain of exclusions.
+let NOT_FRAME = new Set([0xc4, 0xc8, 0xcc]);
+
+// The dimensions live in the frame header, which is the first SOFn marker.
+// SOF2 is a frame like SOF0, so a progressive file is read like a baseline one.
+/** @type {(code: number) => boolean} */
+let isFrame = (code) => code >= 0xc0 && code <= 0xcf && !NOT_FRAME.has(code);
+
+// A PNG carries the two numbers in its IHDR at a fixed offset.
+/** @type {(bytes: Uint8Array) => { width: number, height: number } } */
+let pngSize = (bytes) => ({ width: long(bytes, 16), height: long(bytes, 20) });
+
+/** @type {(bytes: Uint8Array) => { width: number, height: 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 { width: word(bytes, at + 7), height: word(bytes, at + 5) };
+  }
+  return { width: 0, height: 0 };
+};
+
+// One reader per format `sniff` names.
+/** @type {Record<string, (bytes: Uint8Array) => { width: number, height: number }>} */
+let READERS = { png: pngSize, jpeg: jpegSize };
+
+/**
+ * The image's own size in pixels, or null when the header does not carry one
+ * -- bytes whose magic numbers `sniff` vouched for, truncated before the
+ * dimensions. Read, never decoded: a PNG's IHDR and a JPEG's frame header
+ * carry the two numbers, and nothing here looks at a pixel.
+ *
+ * The size rides on the image event beside the format, so every target places
+ * a picture from a field rather than parsing the same two headers again, and a
+ * file too short to state its size fails once, in the engine, for every target
+ * alike (`docs/adr/0067`).
+ *
+ * @param {Uint8Array} bytes The image file.
+ * @param {"png" | "jpeg"} format The format `sniff` named.
+ * @returns {{ width: number, height: number } | null} The size, if readable.
+ */
+export function dimensions(bytes, format) {
+  // Keyed rather than a ternary so the format list lives in one place: a
+  // format `sniff` learns later and this table does not would throw here
+  // rather than be read silently as the one on the ternary's else branch.
+  let size = READERS[format](bytes);
+  // A zero is how either reader says "the header stopped before this" -- an
+  // absent byte reads as zero, and no image is zero wide.
+  return size.width > 0 && size.height > 0 ? size : null;
+}

package/lib/index.d.ts

@@ -506,8 +506,20 @@ export interface TokenStyle {
 /** One static text run of a cell's template, verbatim (sjabloon's literal token). */
 export type LiteralToken = SjabloonLiteralToken & TokenStyle;
 
-/** One interpolation's pre-stringify value (sjabloon's value token). */
-export type ValueToken = SjabloonValueToken & TokenStyle;
+/** Which page value a token *is*, on the two whose interpolation says so. */
+export type PageField = "page.number" | "page.total";
+
+/**
+ * One interpolation's pre-stringify value (sjabloon's value token).
+ *
+ * `field` is present where the interpolation is exactly `{{ page.number }}` or
+ * `{{ page.total }}`. The value is unchanged -- the number this render saw --
+ * and `field` says which page value the token stands for, so a target whose
+ * own document format numbers pages writes a live field there instead
+ * (SCHEMA.md, "Page bands"). Anything computed from a page value carries no
+ * `field`, and a target that paginates itself, or not at all, ignores the key.
+ */
+export type ValueToken = SjabloonValueToken & TokenStyle & { field?: PageField };
 
 export type Token = LiteralToken | ValueToken;
 
@@ -629,6 +641,14 @@ export interface ImageEvent {
   bytes: Uint8Array;
   /** Sniffed from the bytes' magic numbers, so no consumer repeats it. */
   format: ImageFormat;
+  /**
+   * The image's own width in pixels, read from the same header. Bytes too
+   * short to state a size never reach a target: that is a render error on
+   * every target alike.
+   */
+  width: number;
+  /** The image's own height in pixels, read from the same header. */
+  height: number;
   fit: ImageFit;
   /** The rendered `alt` template, present when the item declares one. */
   alt?: Token[];
@@ -900,6 +920,33 @@ export function isDiagnostic(e: unknown): e is QuarioDiagnostic;
  */
 export function imageError(path: string | undefined, said: string, cause?: unknown): Error;
 
+/** Optional document information; never includes dates, so output stays deterministic. */
+export interface QuarioMeta {
+  title?: string;
+  author?: string;
+  subject?: string;
+}
+
+/**
+ * Close a **target factory's** option key set, for the target itself to call.
+ * A target refuses what it does not understand at the factory call, so a
+ * host's typo costs one stack trace where they wrote it rather than an option
+ * silently lost. Throws a `TypeError` prefixed with `at`.
+ *
+ * Nullish is absence. Own enumerable keys only, so an inherited property is
+ * not reported back as an option the host wrote.
+ */
+export function hostOptions<T>(value: T, keys: readonly string[], at: string): T;
+
+/**
+ * Validate a target's `meta` option whole: `title`, `author` and `subject`,
+ * each a string, and nothing else. Every document target takes the same three,
+ * so the contract is checked once; the name each property carries inside a
+ * given format stays that target's own. Throws a `TypeError` prefixed with
+ * `at`.
+ */
+export function hostMeta<T extends QuarioMeta | null | undefined>(value: T, at: string): T;
+
 /**
  * Join a token stream to display text: literals verbatim, values through
  * `display()`. Re-exported from sjabloon.

package/lib/index.js

@@ -34,6 +34,7 @@ export {
   STYLE_NAMES,
 } from "./style.js";
 export { imageError, isDiagnostic } from "./locate.js";
+export { hostMeta, hostOptions } from "./host.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */
 

package/lib/license.js

@@ -5,18 +5,18 @@
 // Verification is entirely offline, and asynchronous only because WebCrypto
 // is.
 
-// Release date of this version, written into the version commit by
-// release-please (`x-release-please-date`). Both constants keep the `let`
-// spelling that `scripts/license/keygen.mjs` matches on, though nothing
-// reassigns them. A key is valid for every version released inside its window
+// Release date of this version, written into the Version PR's commit by
+// `scripts/stamp-release-date.mjs` (the `release-date` mark). Both constants
+// keep the `let` spelling that `scripts/license/keygen.mjs` matches on,
+// though nothing reassigns them. A key is valid for every version released inside its window
 // (LICENSE section 7), so validity compares ISO date strings and never reads
 // a clock — accepted output stays accepted.
-let RELEASE = "2026-09-07"; // x-release-please-date
+let RELEASE = "2026-09-15"; // release-date
 // The verifying half of the signing pair: the 65-byte uncompressed P-256
 // point, base64url. The private half never enters the repo;
 // scripts/license/sign.mjs mints keys against it.
 let PUBKEY =
-  "BEyXC0sH4pDoL-gGxLTqHguWi38WK2v7OrAfNvK8_4Ou8yLhcKgX5dzCoj1ojj6ez0B1cwMDPfejthqEQ4wZGjM";
+  "BLT0Rp5dYp7U6qiaBO5GfEx5lOntJZAbCrbmEfE824dHhdEzfylChU7xUEDj5jnArxSjXaTu8jnBPD8MX5FbNik";
 
 // The marking wording, stated once for the whole engine and carried to every
 // target on `report-start` (SCHEMA.md, "License keys"): the targets own where

package/lib/plan.js

@@ -51,7 +51,8 @@ import { ANCHORS, BLOCKED, NAME, RESERVED, record } from "./names.js";
 import { MATH } from "./math.js";
 import { REDUCERS, reducerFor } from "./reducers.js";
 import { aggregateValue, withRow } from "./scope.js";
-import { oneValue, opt, sameStyle, sniff } from "./stream.js";
+import { dimensions, sniff } from "./image.js";
+import { oneValue, opt, sameStyle } from "./stream.js";
 import {
   checkBorderSides,
   checkCellStyle,
@@ -482,10 +483,28 @@ let runProp = (expression, path, source) => (scope) => {
     locate(path, source, error, expression.isDiagnostic(error) && relocateXprsn, 1);
   }
 };
+// The [live field](../../../CONTEXT.md#live-field): which page value a token
+// *is*, for a target whose own format numbers pages. sjabloon offers each
+// interpolation's expression source once, while compiling, which is the only
+// place the words the author wrote still exist -- a rendered token carries the
+// number and nothing about where it came from. Reading the source here instead
+// is what hard constraint 2 forbids, and a sentinel bound to `page.number` was
+// ruled out because xprsn's `==` is strict: it would break `=page.number == 1`.
+//
+// One table for the whole compile: the answer depends on the expression alone,
+// never on where the cell sits. A Map rather than a lookup object, because the
+// key is author source and nothing reached through `Object.prototype` is an
+// answer to this question; each name is written once and is its own answer,
+// frozen because every cell that says it shares the one object.
+const PAGE_FIELDS = /** @type {Map<string, { field: import("./index.js").PageField }>} */ (
+  new Map(["page.number", "page.total"].map((field) => [field, Object.freeze({ field })]))
+);
+/** @type {(expr: string) => { field: import("./index.js").PageField } | undefined} */
+let pageField = (expr) => PAGE_FIELDS.get(expr);
 /** @type {(src: string, path: string, source: any, FNS: any, BND: Set<string>) => any} */
 let compileCell = (src, path, source, FNS, BND) => {
   try {
-    return template(src, FNS, { bound: BND });
+    return template(src, FNS, { bound: BND, tag: pageField });
   } catch (error) {
     locate(path, source, error, isTemplateDiagnostic(error) && relocateTemplate);
   }
@@ -1326,28 +1345,35 @@ let nodes = (
   let altOf = (def, path) => (def.alt != null ? textValue(def.alt, path + ".alt") : null);
   /** @type {(alt: any, scope: Scope) => any} */
   let imageAlt = (alt, scope) => alt && alt(scope);
+  // The two places `locate` originates an error instead of re-throwing a
+  // caught one: each fault is quario's own verdict on the bytes, so it carries
+  // the location every other render error does and, having no engine
+  // diagnostic behind it, stays out of `isDiagnostic`.
+  /** @type {(fields: any, message: string) => never} */
+  let badImage = (fields, message) =>
+    locate(fields.path + ".source", fields.sourceSpec, TypeError(message));
   /** @type {(fields: any, scope: Scope, bytes: any) => any} */
   let imageEvent = (fields, scope, bytes) => {
-    // The bytes stay bytes. Sniffing reads their magic numbers -- it never
-    // decodes the image, and nothing here turns them into a string -- and
-    // the answer rides on the event so no target sniffs a second time.
+    // The bytes stay bytes. Reading them touches the magic numbers and the
+    // header the size lives in -- never a pixel, and nothing here turns them
+    // into a string -- and both answers ride on the event so no target reads
+    // the same header a second time.
     let format = sniff(bytes);
-    // The one place `locate` originates an error instead of re-throwing a
-    // caught one: the fault is quario's own verdict on the bytes, so it
-    // carries the location every other render error does and, having no
-    // engine diagnostic behind it, stays out of `isDiagnostic`.
-    if (!format)
-      locate(
-        fields.path + ".source",
-        fields.sourceSpec,
-        TypeError("expected a Uint8Array of PNG or JPEG bytes"),
-      );
+    if (!format) badImage(fields, "expected a Uint8Array of PNG or JPEG bytes");
+    let size = dimensions(bytes, format);
+    // The one thing the engine reads past the magic numbers, and so the one
+    // header failure every target shares: a file that cannot state its size
+    // can be placed by none of them (`docs/adr/0067`). Past the size the
+    // engine still vouches for nothing.
+    if (!size) badImage(fields, "could not read the image's size from its bytes");
     return opt(
       {
         type: "image",
         role: fields.role,
         bytes,
         format,
+        width: size.width,
+        height: size.height,
         fit: fields.fit,
         path: fields.path,
       },

package/lib/stream.js

@@ -207,29 +207,6 @@ export function isReportBand(role) {
   return REPORT_BANDS.has(role);
 }
 
-// The two raster formats an image item may carry, as the bytes announce
-// themselves: PNG's 8-byte signature and JPEG's start-of-image marker. Read,
-// never decoded -- the engine answers which format the bytes are, not what
-// they depict.
-let PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-let JPEG = [0xff, 0xd8, 0xff];
-
-/**
- * The image seam: name the format a `source` expression's bytes hold, or null
- * when they are not image bytes at all -- including when they are not bytes.
- * The traversal sniffs once per image event and the answer rides on the event,
- * so no consumer repeats it.
- *
- * @param {any} bytes The value a `source` expression yielded.
- * @returns {"png" | "jpeg" | null} The format, or null when unreadable.
- */
-export function sniff(bytes) {
-  if (!(bytes instanceof Uint8Array)) return null;
-  if (PNG.every((byte, i) => bytes[i] === byte)) return "png";
-  if (JPEG.every((byte, i) => bytes[i] === byte)) return "jpeg";
-  return null;
-}
-
 // The cooperative hand-back's plumbing. A timer is the slowest way a runtime will
 // hand the loop back and, until this landed, the only one quario used: measured
 // on an M-series Mac it costs ~1.20ms per hand-back against ~0.015ms for

package/lib/style.js

@@ -375,7 +375,8 @@ export let checkRunStyle = narrowed(RUN_STYLES, "a styled run");
 export let checkSlotStyle = withoutFlow(checkStyle, "a split slot");
 // `valign` is legal exactly where a box has height it did not ask for
 // (CONTEXT.md "Box": slack). A slot's box is the split's height, so a slot --
-// text or image -- reads it; a band image's box is its own, so it does not.
+// text or image -- reads it; a band image's box is exactly its picture's
+// height, so it does not.
 // That is the one name an image accepts in a slot and nowhere else, the same
 // shape of reason `width` reaches an item only there (docs/adr/0029).
 let SLOT_IMAGE_STYLES = [...IMAGE_STYLES, "valign"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "padvinder": "^0.9.0",
-    "sjabloon": "^0.12.0",
+    "sjabloon": "^0.13.0",
     "xprsn": "^0.11.1"
   },
   "devDependencies": {