quario 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,15 +1,178 @@
-# Changelog
+# 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
+  HTML, which was the only place `<b>` in a template ever meant anything. A run
+  carries the inline declarations only: no padding, borders or spacing, which
+  belong to a whole line or block.
+
+  A cell's tokens carry a run's resolved style on the tokens it covers, and
+  `styledRuns(tokens)` groups them back out — the same rule every built-in
+  target reads them through, so a custom target cannot drift from them.
+  `RUN_STYLE_NAMES` is the inline half of the vocabulary as a list, beside
+  `STYLE_NAMES`, for a tool that offers an author what a run may wear.
+
+- **`plan()` now reports declarations that nothing will read.** A definition can
+  be perfectly valid and still say something the engine quietly drops, and
+  until now the only way to find out was to notice the output was wrong.
+  `plan()` returns a `warnings` list beside `problems` — same shape, same
+  document order, one entry per declaration — and it currently catches three:
+
+  - a `format` on a cell whose value can never present a single interpolation —
+    `"Due {{ due }}"` under `format: "date"` — which the engine leaves unread;
+  - a `currency` on a cell whose `format` is not `"currency"`, which the engine
+    reads only under that kind and otherwise ignores, so the cell renders in
+    the instance's currency and the code you wrote does nothing;
+  - a table where every column declares a `width` and the widths total under
+    100, which leaves the trailing share of the table unused — usually a column
+    edited down without its neighbours being adjusted.
+
+  `problems` is unchanged and still fatal: a definition with problems compiles
+  to nothing, while one carrying only warnings compiles and renders exactly as
+  before. Hosts that ignore the new field are unaffected, and `validate()` is
+  untouched.
+
+  Warnings are advisory and deliberately incomplete — they catch what can be
+  seen in the definition alone, without data, so a quiet `warnings` list is not
+  a promise that every declaration will be read.
+
+- **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
+  `"{{ amount }} of {{ quantity }}"` under `format: "currency"` rendered the
+  quantity as money too — and the page and the spreadsheet disagreed about it,
+  the page formatting inside a sentence where the sheet did not.
+
+  A cell `value` may now be a list of **styled runs** —
+  `{ "value": "…", "style": { … } }` — each with its own declarations, and
+  `format` applies to a run holding a single interpolation.
+
+  **What changes in an existing report:** a cell that mixes text and an
+  interpolation under a `format` stops presenting that value and renders it
+  plainly, in every target. `"Due {{ due }}"` with `format: "date"` was
+  `Due 14 Aug 2026` on the page and `Due 2026-08-14` in the sheet; it is now
+  the plain form in both. To restore it, split the value and leave the
+  declaration where it is:
 
-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.6.0] - 2026-09-07
+  ```jsonc
+  {
+    "value": [{ "value": "Due " }, { "value": "{{ due }}" }],
+    "style": { "format": "date" }
+  }
+  ```
 
-### Added
+  A cell's `format` reaches its runs, so nothing moves and nothing is declared
+  twice. `plan()` reports the cells this affects wherever it can see them
+  without data.
+
+- **`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
+  `{{ round(@.qty * @.price, 2) }}` paid for one per row. A hundred-thousand
+  row report with two such columns drained in 3.5 s; it now drains in 0.2 s.
+  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
+  the function, as a reducer's already did. The located path still names the
+  cell — one cell holds as many calls as you write, which is the whole reason
+  the name is worth having.
+
+  **An `n` that cannot be read as a number at all now gets the same answer.**
+  A `BigInt` or a `Symbol` reaching `n` from render data used to surface the
+  runtime's own `Cannot convert a BigInt value to a number`, and an object
+  carrying a throwing `valueOf` surfaced whatever it threw — each located at
+  the cell but naming neither the function nor anything an author could act
+  on. All of them are now the same refusal.
+
+- **`isDiagnostic` is documented for what it actually answers.** The README
+  said it was true for "one of the stack's located errors: quario's own, or one
+  thrown directly by xprsn, sjabloon, or padvinder", and its example read a
+  `false` as "one of your own functions failed". Only an engine's own error is
+  a diagnostic: quario's verdicts on a document — an unknown reducer, a
+  misused inline reducer, image bytes it will not vouch for — are located just
+  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
+  internals, naming neither the reducer nor the mistake. It now reads
+  `min is a reducer over an array, not a scalar function; got a number`, and a
+  second argument that is not a lambda says so in the same words rather than
+  reaching a host as `of is not a function`. Register a function of your own to
+  shadow a built-in reducer when a report needs the scalar.
+
+  **Two reducers used to answer instead of failing**, each reading a `length`
+  off a value that is not a collection: `count('ab')` presented `2` — a
+  string's own length, folded as if it were a count of rows — while `count(1)`
+  and `avg(1, 2)` presented nothing at all. All three are now the same located
+  error. A reducer over an **absent** array is unchanged and still not a
+  mistake: `sum(@.lines)` on a row carrying no lines is `0`, exactly as an
+  empty array gives.
+
+## 0.6.0
+
+### 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
@@ -18,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,
@@ -74,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.
@@ -134,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
@@ -162,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
@@ -312,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
@@ -363,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
@@ -393,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
@@ -417,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`
@@ -442,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
@@ -468,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
@@ -485,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
@@ -495,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`),
@@ -517,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
@@ -537,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
@@ -549,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,
@@ -574,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
@@ -604,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 —
@@ -619,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
@@ -644,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
@@ -656,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
@@ -664,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
@@ -675,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)`
@@ -127,6 +136,14 @@ display text. Passing the cell's resolved `format` kind opts into the seam's one
 real numeric cells;
 [`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
 
+### `styledRuns(tokens)`
+
+Groups a cell's tokens into its **styled runs**, in order — each `{ style, tokens }`,
+with `style` `null` where the tokens carry none and the cell's own applies. Consecutive tokens
+with equal styles are one run, which is lossless: equal styles render identically, so the grouping
+survives a JSON round trip. Every built-in target reads a cell's runs through this, so a custom
+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
@@ -154,7 +171,8 @@ cell the same way:
 - `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.
-- `STYLE_NAMES` — the closed style vocabulary, in the spec's order.
+- `STYLE_NAMES` — the closed style vocabulary, in the spec's order, and
+  `RUN_STYLE_NAMES` — the inline half of it, which is what a styled run may wear.
 
 ### `validate(schema, functions?)`
 
@@ -172,34 +190,49 @@ so `validate()` can never disagree with what `report()` accepts.
 ### `quario().plan(schema, functions?)`
 
 The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns
-`{ report, problems, anchors }`: the compiled report (`null` while the document has problems),
-every problem structurally as `{ path, source?, message, diagnostic? }` (the `message` is exactly
-`validate()`'s string, and every problem keeps its own located diagnostic with `start`/`end`
-offsets, not only the first), and `anchors`, mapping each compiled source's schema path to the
-anchors and group handles it reads — the unfiltered complement of `names`.
+`{ report, problems, anchors, warnings }`: the compiled report (`null` while the document has
+problems), every problem structurally as `{ path, source?, message, diagnostic? }` (the `message`
+is exactly `validate()`'s string, and every problem keeps its own located diagnostic with
+`start`/`end` offsets, not only the first), `anchors`, mapping each compiled source's schema path
+to the anchors and group handles it reads — the unfiltered complement of `names` — and
+`warnings`.
+
+A warning is `{ path, source?, message }`: the document declares something nothing will read. It
+is not a problem at a lower severity, which is why it has no `diagnostic` — nothing raised, the
+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
+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.
 
 ```js
-const { report, problems, anchors } = quario().plan(schema);
+const { report, problems, anchors, warnings } = quario().plan(schema);
+for (const warning of warnings) console.warn(warning.message);
 if (report) await report.render(html(), data);
 else console.error(problems[0].path, problems[0].message);
 ```
 
 ### `isDiagnostic(error)`
 
-True when a caught value is one of the stack's located errors: quario's own, or one thrown
-directly by xprsn, sjabloon, or padvinder. Authentication checks identity. An error that only
-matches the shape does not pass.
+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.
 
-Located errors name their band path and offending source while keeping their original type
-(`SyntaxError`, `TypeError`, `RangeError`). They carry `code`, `start`/`end` offsets, and (for
-query budget failures) `limit` and `actual`.
+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
+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
+of those offsets, `limit` and `actual`.
 
 ```js
 try {
   await report.render(html(), data);
 } catch (e) {
-  if (isDiagnostic(e)) console.error("report problem:", e.message);
-  else throw e; // one of your own functions failed
+  // Every error names where it failed; a diagnostic also carries an engine's own metadata.
+  if (isDiagnostic(e)) console.error(e.code, e.start, e.end);
+  throw e;
 }
 ```
 
@@ -232,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
@@ -248,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