quario 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,15 +1,61 @@
-# 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.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 +93,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 +122,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 +130,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 +153,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 +170,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 +181,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 +236,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 +294,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 +318,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 +465,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 +511,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 +540,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 +564,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 +586,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 +612,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 +626,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 +636,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 +655,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 +670,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 +682,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 +704,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 +732,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 +745,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 +765,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 +776,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 +783,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 +791,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

@@ -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 this page was rendered with; `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
 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)`
@@ -256,7 +265,8 @@ Markdown target lives in the repository at `example/markdown.js` in about 70 lin
 targets are written against 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,6 +282,13 @@ 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

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[];

package/lib/license.js

@@ -5,13 +5,13 @@
 // 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-14"; // 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.

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.8.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": {