quario 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,441 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- **`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
+  further, so every failure past them belongs to whichever target was sizing or
+  embedding the file — and each was wording it its own way. This names the item
+  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,
+  the currency code, and for a date its form and timezone. A report of a
+  hundred thousand formatted cells in mixed currencies went from 3.2 s to
+  0.2 s rendering to HTML. Nothing about what a cell presents changes.
+
+  The store is bounded and empties past its bound rather than growing, so a
+  report presenting an unusual number of distinct formats costs what it always
+  did and never a formatter belonging to another cell.
+
+- **`format` takes a digit count, and a date takes a form.** The declaration is
+  still a closed kind, and now the kind may carry the one modifier it
+  understands: `number`, `percent` and `currency` take `digits`, and `date`
+  takes `form`.
+
+  ```jsonc
+  { "header": "Rate",  "value": "{{ @.rate }}",
+    "style": { "format": { "kind": "percent", "digits": 3 } } }
+  { "header": "Total", "value": "{{ @.amt }}",
+    "style": { "format": { "kind": "currency", "digits": 0 }, "currency": "EUR" } }
+  { "header": "Due",   "value": "{{ @.due }}",
+    "style": { "format": { "kind": "date", "form": "long" } } }
+  ```
+
+  The bare kind stays the shorthand — `"number"` means
+  `{ "kind": "number" }` — so no existing declaration has to change.
+
+  `digits` is a whole number from 0 to 20 and overrides the count the kind
+  would otherwise present, **a currency's minor units included**: the example
+  above shows `€1,235` on the page and builds `"EUR"#,##0` in the worksheet.
+  The minor units remain the default, so a JPY cell still shows no decimals
+  beside a EUR one that shows two.
+
+  On `percent`, `digits` counts the places of the **presented percentage**, not
+  of the stored fraction: `digits: 2` on `0.12345` gives `12.35%`. Making the
+  stored value agree still takes `round(x, 4)` — the two count different
+  things, a factor of 100 apart.
+
+  `form` is one of `short`, `medium`, `long`, `full`. It is honoured exactly in
+  HTML and PDF, and **approximated in the worksheet**: a sheet date is a real
+  typed date its reader re-presents, so the shape is yours while the language a
+  month or weekday name is spelled in follows whoever opens the file. Pinning
+  that would stop the sheet reading naturally for its reader.
+
+  A modifier a kind does not understand is a definition error naming the cell —
+  `{ "kind": "date", "digits": 2 }` fails, as does a `digits` outside 0 to 20.
+  `format` layers whole: a cell that names it restates the whole declaration, so
+  naming a kind again resets the modifier. Only the whole declaration may be an
+  `=` expression; a computed count is written
+  `"={'kind':'number','digits':@.dp}"`. Custom `#,##0.00` patterns still belong
+  in `funcs`, and a fraction-digit count no longer needs one.
+
+- **`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.
+
+  ```jsonc
+  { "header": "Amount", "value": "{{ @.amt }}",
+    "style": { "format": "currency", "currency": "=@.ccy" } }
+  ```
+
+  Until now the code lived only on the instance, so a report whose rows arrive
+  in different currencies — a revenue listing, a statement, an outstanding-
+  invoices table — had to format through `funcs`, and that costs the value: a
+  formatter returns a string, so the cell leaves the typed seam and the
+  worksheet gets text with no number format. A declared code keeps the number.
+
+  The cell's own code beats the instance's, which stays the default for
+  documents that only ever hold one denomination. Locale and timezone do not
+  follow it into the document: a locale describes the reader, while a currency
+  code describes the value. The declaration takes an expression like any other,
+  so a total under a group keyed by currency reads `"=byCcy.key"`. It shares
+  `format`'s sites exactly — text items, column cells, headers and totals, and
+  a column's own `style.currency` declares an amount column once — and, like
+  `format`, it is refused on an image, on `row.style` and on the report
+  default. It is unread without `format: "currency"`.
+
+  A literal that is not three uppercase letters is a definition error. An
+  expression that resolves to something else stays lenient, and the cell then
+  renders as plain display text: it does **not** fall back to the instance's
+  currency, because labelling a figure in a denomination nobody named is worse
+  than not formatting it.
+
+- **`round`, `floor`, `ceil` and `abs` are callable from any expression**,
+  without registering anything. `round(x, n)` gives `x` to `n` decimal places;
+  `n` defaults to 0 and must be a number from 0 to 100; a fraction in it
+  truncates. This is the lever a report needs when arithmetic across exact values lands on an inexact one:
+  a receipt whose `{{ $.subtotal + $.vatLow + $.vatHigh }}` computes
+  `83.75999999999999` writes `83.76` once the sum is wrapped in `round(…, 2)`.
+  It matters in the two targets that keep the number rather than presenting it
+  — the workbook stores the value, and a CSV field shows it as text with no
+  number format to hide behind. A registered function of the same name still
+  wins, so nothing an existing report does changes.
+
+  They round the **decimal you wrote**, not the binary value it is stored as:
+  `round(2.675, 2)` is `2.68` and `round(0.615, 2)` is `0.62`. Note that a
+  `percent` cell presents its value multiplied by 100, so matching a
+  two-decimal percent display takes `round(x, 4)`. A value that is not a finite
+  number passes through untouched rather than becoming zero; an `n` outside the
+  range is an error naming the cell it came from.
+
+- `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
+  the four forms you can now ask for. It renders `Aug 14, 2026` instead, and
+  `14 Aug 2026` under `en-IE`. In the worksheet the number format moves from
+  `yyyy-mm-dd` to `dd mmm yyyy`.
+
+  If you want the old shape back, say so: `{ "kind": "date", "form": "short" }`
+  is the nearest of the four. This is the one change here that moves output
+  under an existing report.
+
+- **`style.format` crosses the event stream resolved, not as authored.** A
+  custom target reading `style.format` now sees `{ kind, digits }` or
+  `{ kind, form }` where it saw a bare string: `"number"` arrives as
+  `{ kind: "number", digits: 2 }` and `"date"` as
+  `{ kind: "date", form: "medium" }`. A `currency` whose code cannot be read
+  arrives as `{ kind: "currency" }` with no count at all, which is the signal
+  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
+  answered, even a value the vocabulary rejects; every other name was already
+  dropped. It is now dropped too, so one rule covers the whole vocabulary and
+  `currency` is its only exception.
+
+  Nothing a report renders changes. A border side is still won whole by the
+  node that names any of its three parts — that is now settled from the
+  declarations rather than from what they resolve to, so a rejected part still
+  cannot hand the node its row's other two. A side left incomplete still
+  contributes nothing rather than becoming a solid black stroke, and a rejected
+  padding still falls to the target's own inset.
+
+  What changes is what a consumer reading the stream itself sees. Where a cell
+  had `style.borderTopColor` holding an unusable value, the key is now absent:
+
+  ```js
+  // before
+  cell.style; // { borderTopWidth: 1, borderTopColor: "2-6-A-2-2" }
+  // after
+  cell.style; // { borderTopWidth: 1 }
+  ```
+
+  Every target in this release already checked such values before reading them
+  and is unaffected. A consumer that inferred border-side ownership from which
+  keys were present should read the declarations instead; one that validates
+  what it reads needs no change.
+
+- **`format()` now takes the cell's resolved `style` instead of its `format`
+  kind.** The signature is `format(value, style, options)`, where it was
+  `format(value, kind, options)`. This is what lets the helper read a cell's own
+  `currency` code alongside the kind. Callers pass one property less:
+
+  ```js
+  // before
+  format(token.value, style?.format, intl);
+  // after
+  format(token.value, style, intl);
+  ```
+
+  A caller holding only a kind wraps it as `{ format: kind }`.
+
+- **A table's `total` is now a block holding its rows**, so what belongs to the
+  totals as a whole can be said once. Before, `total` was the array of rows
+  itself:
+
+  ```jsonc
+  "total": [{ "cells": [...] }, { "cells": [...] }]
+  ```
+
+  Now it is an object whose `rows` is that same array, plus a `style` and a
+  `visible` of its own:
+
+  ```jsonc
+  "total": {
+    "style": { "paddingTop": 0, "paddingBottom": 0 },
+    "rows": [{ "cells": [...] }, { "cells": [...] }]
+  }
+  ```
+
+  The rows themselves are unchanged — still `{ "cells", "style?", "visible?" }`,
+  still covering every column exactly once. A `total` that is still an array is
+  a definition error reading `detail.total: expected an object`, and a `total`
+  with no `rows` reads `detail.total.rows: expected an array`. Total cell paths
+  gain the one segment: `detail.total.rows[r].cells[i]`, which is what a
+  `total-row` cell now carries as its `path` and what a located problem names.
+
+  The block's `style` is the layer below each row's — box under box, every
+  other declaration under the row's own — and takes a total row's vocabulary,
+  the whole style set less flow spacing and `format`. Where the block, a row
+  and a cell all speak, the innermost one that names any of a border side's
+  three keys takes that side whole, exactly as a cell already did over a row;
+  padding layers per name. Exact `false` on the block's `visible` omits the
+  totals entirely: the rows are never evaluated, none of them votes on a
+  width-less column, and the output is what leaving `total` out gives.
+
+  This is why the change earns a break: a table's header row has `detail.header`
+  and its data rows have `detail.row`, but the totals — the one kind whose rows
+  a document writes out one by one — had no level above them, so "these sit at
+  the band's line pitch, not the table's row pitch" had to be spelled on every
+  row. `columns` is unaffected and needs no such block: a declaration reaching
+  every column reaches every data cell, which is what `detail.row`'s style
+  already says from the other side.
+
+- **`table-start` now carries the header row**, instead of a `header` cell on
+  each column that a custom target had to collect for itself. The event's
+  `header` is `{ cells, style? }` — the same shape a `row` or `total-row`
+  event has — where `cells` holds one cell per column no neighbour's `span`
+  covers, so it is shorter than `columns` whenever a header spans. Each header
+  cell carries its column's `path`, as a row cell does; a spanning header takes
+  the first column it covers. What is left on `columns` is the geometry: one
+  entry per column, holding a `width` percentage when the document authored
+  one. Nothing an existing report produces changes in any of the shipped
+  targets — this is the seam between the engine and a target, not the document.
+
+  ```js
+  // before
+  const headers = event.columns
+    .filter((column) => column.header)
+    .map((column) => Object.assign({}, column.header, { path: column.path }));
+  const headerStyle = event.style;
+
+  // after
+  const headers = event.header.cells;
+  const headerStyle = event.header.style;
+  ```
+
+  `columns[i].header`, `columns[i].path` and `table-start.style` are gone. A
+  target that reads only `columns[i].width` is unaffected.
+
+- **`format` now presents a fixed number of fraction digits, and every target
+  presents the same number.** Until now the digits were whatever each edge
+  happened to default to: `format: "number"` showed up to three decimals in
+  HTML and PDF and exactly two in a worksheet, and `format: "percent"` showed
+  none in HTML and PDF against the worksheet's two — so one cell in one
+  document read `12%` in the PDF and `12.35%` in the workbook beside it.
+
+  `number` and `percent` are now **two places, always**, in every target that
+  presents. `currency` is its currency's own minor units, so a JPY amount has
+  none and a BHD amount has three, where every currency previously got two.
+  Author-visible, with no document change:
+
+  | value              | before      | now        |
+  | ------------------ | ----------- | ---------- |
+  | `number` `1000`    | `1,000`     | `1,000.00` |
+  | `number` `0.12345` | `0.123`     | `0.12`     |
+  | `percent` `0.21`   | `21%`       | `21.00%`   |
+  | `currency` JPY     | `¥1,234.57` | `¥1,235`   |
+
+  Only the digit count converges. Grouping separators, a currency symbol's
+  position and a date's shape still follow each target's own conventions, and
+  in a worksheet they follow whoever opens the file. `date` is unchanged.
+  A report that needs different digits formats through `funcs`, as before.
+
+- 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
+  style rather than passed on, so no target has to decide what an unreadable
+  value means.
+
+  Before, the value reached each target and they disagreed. A detail item with
+  `"bold": "=@.flag"` over a `1` rendered bold in a PDF and a worksheet but not
+  in HTML. On a report header, where those two targets carry a heavier default
+  of their own, a `0` rendered _not_ bold in both while HTML left the header
+  bold. The same held for every other declaration: a report header whose
+  `"size": "=@.pt"` resolved to `"big"` rendered at 14pt in HTML, at the body
+  size in a PDF, and at no size at all in a worksheet. Now all three keep the
+  layer below in every case, and only a real `false` turns a flag off.
+
+  This covers `family`, `size`, the five flags, `color`, `background`, `align`,
+  `valign`, `format`, `spaceBefore` and `spaceAfter`, and only where the value
+  comes from an `=` expression — a literal has always been checked when the
+  report was compiled. It reaches inside a split too: a slot whose `format`
+  expression resolves to something other than the four kinds now keeps the
+  split's own kind instead of overwriting it.
+
+  Two declarations are deliberately unchanged. A border or padding name is kept
+  rather than dropped, because a node that names any part of a border side
+  takes that side whole from its row — dropping the name would hand the node
+  the row's other two and draw an edge nobody declared. And a `currency` code
+  that is not a code still crosses as `null` rather than disappearing, so a
+  cell that named a denomination is never presented under another one.
+
+- A `format` kind that an `=` expression resolved to the name of a built-in
+  object member — `"toString"`, `"constructor"` — now contributes nothing and
+  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
+  the band below the box would push that band off the pin, so it is refused.
+  Which band is below the box was read too narrowly, and which item leads it
+  too eagerly.
+
+  Reports that used to validate and now do not: a lead on the `empty` band's
+  first item, and a lead on a group header below the first one. Both were
+  already refused at render, but only on the render that reached them — an
+  `empty` band's lead detonated the first time a filter emptied the row set,
+  on a report that had validated clean for months. Both are definition errors
+  now, on every render.
+
+  Reports that used to be refused and now validate: a lead on an item that may
+  not appear at all — one whose `visible` is an expression, or an image whose
+  `source` yields nothing. Such an item was blamed as though it always
+  occupied, so a document that renders correctly could not be compiled. The
+  check now stays silent wherever only the data decides which item comes first,
+  and the render refuses it at the moment the answer exists.
+
+  Two smaller repairs come with it. A `spaceBefore` that is not a paintable
+  number — negative, `NaN`, infinite — no longer produces two problems on one
+  key, one telling you to make it `0` and one telling you it is not a valid
+  measurement; only the second is reported, because it is the one that is
+  wrong. And a `split` that leads a band now names itself in the error rather
+  than reporting against the report header, which is a band this rule never
+  covers.
+
+## [0.5.0] - 2026-09-05
+
+### Added
+
+- **`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
+  vocabulary — the editor's style rail — reads it from here instead of
+  carrying a copy that has to learn each new name.
+- **`span` lets a cell cover several table columns**, so a label reaches across
+  them instead of being pushed sideways by empty cells. A literal positive
+  integer; absent is 1. It is legal on the two cells a document writes: a
+  column's `header`, where the columns it covers omit their own `header`, and a
+  total row's cells, whose spans must sum to the column count exactly. A data
+  row's cells are the columns' own, so there is no cell there to carry one — a
+  line that runs across the table is a `split` item below it. A span covers and
+  does not vote: a cell over more than one column has no say in their widths,
+  and a column nothing votes on takes the cell-padding floor.
+- **`valign`** joins the style vocabulary: `"top"`, `"middle"` or `"bottom"`,
+  a literal or an `=` expression like `align`. It is legal exactly where a box
+  is taller than its content asked for — table cells, headers, totals, `row`,
+  and split slots, text or image — and a definition error on a stacked item and
+  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`
+  reached no cell at all: a fragment dropped them, a worksheet turned them into
+  an edge on each cell, and a page drew one box around the row. Now they layer
+  under each cell's own, the way `bold` and `valign` on a row already did, so
+  one declaration means one thing everywhere.
+  What this makes possible is declining the cell padding a row at a time:
+  `"paddingTop": 0, "paddingBottom": 0` on `detail.row` sets the pitch for
+  every data row, where before it had to be written on each cell.
+  Two things move for documents that already declared a box on a row.
+  A row's `borderLeft` is now an edge on each of the row's cells rather than
+  one at the row's outer left — write it on the first column's cells to get the
+  single edge back. And a row's border now occupies height, as a cell's border
+  always has, so a bordered row is taller by its border's width.
+  A border side is won whole by the cell: a cell naming any of that side's
+  three keys takes the side entirely, so a cell that failed soft on one name
+  does not inherit the row's other two.
+  On the event stream, a `row`, `total-row` or `table-start` `style` now
+  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
 
 ### Changed

package/README.md

@@ -51,9 +51,10 @@ surface at compile time, so compile at startup and render in your request path.
 
 ### `quario(options?)`
 
-Creates a configured instance with host-level controls: `{ query?, license? }`. Returns
-`{ report, license }`. `license` settles with this instance's key verification as
-`{ licensed, licensee?, id? }`.
+Creates a configured instance with host-level controls: `{ query?, license?, locale?, currency?,
+timeZone? }` — the query budget, the license key, and the `format` configuration (`en-US`, no
+default currency, UTC). Returns `{ report, plan, license }`. `license` settles with this instance's
+key verification as `{ licensed, licensee?, id? }`.
 
 ### `report(schema, functions?)`
 
@@ -62,7 +63,8 @@ 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 at compile time, like any other definition error.
+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
 report header may interpolate a report aggregate. Event emission pulls on demand, so a consumer
@@ -72,27 +74,29 @@ The compiled report carries metadata:
 
 ```js
 report.names; // free variable names the expressions read, excluding engine anchors
-report.functions; // registry function names the definition calls
+report.functions; // { name, arity } per registry function the definition calls
 report.paths; // padvinder's deeply frozen dependency topology for the `data` query
 ```
 
 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
-row, an optional `total-row`, and `table-end`.
-
-| Event          | Carries                                                                                     |
-| -------------- | ------------------------------------------------------------------------------------------- |
-| `report-start` | `params`, resolved report `aggregates`, optional `page` band closures, `columns`, `marking` |
-| `item`         | `role`, `path`, `tokens`, optional `style`, `run`                                           |
-| `image`        | `role`, `path`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`  |
-| `group-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `reset`, `columns`          |
-| `group-end`    | `name`, `depth`                                                                             |
-| `table-start`  | `path`, `columns` (each `header`, `path`, optional `width`)                                 |
-| `row`          | `cells`, optional `style`, `run`                                                            |
-| `total-row`    | `cells`                                                                                     |
-| `table-end`    | -                                                                                           |
-| `report-end`   | -                                                                                           |
+row, one `total-row` per emitted total row, and `table-end`.
+
+| Event          | Carries                                                                                                                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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-end`    | -                                                                                                                                                                                                                   |
+| `group-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `reset`, `columns`                                                                                                                                  |
+| `group-end`    | `name`, `depth`                                                                                                                                                                                                     |
+| `table-start`  | `path`, `header` (`cells`, optional `style`), `columns` (each an optional `width`)                                                                                                                                  |
+| `row`          | `cells`, optional `style`, `run`                                                                                                                                                                                    |
+| `total-row`    | `cells`, optional `style`                                                                                                                                                                                           |
+| `table-end`    | -                                                                                                                                                                                                                   |
+| `report-end`   | -                                                                                                                                                                                                                   |
 
 **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
@@ -106,19 +110,21 @@ 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. No shipped target honors it yet;
+page column count when present. `@quario/pdf` and `@quario/html` lay page columns out;
 xlsx never will.
 
 ### `text(tokens)`
 
-Joins a token stream to display text: literals verbatim, values as `String(value ?? "")`, run
-styles ignored. Re-exported from sjabloon so consumers do not hand-roll the join.
+Joins a token stream to display text: literals verbatim, values through `display()` (a `Date`
+as ISO 8601, nullish as the empty string), run styles ignored. Re-exported from sjabloon so consumers do not hand-roll the join.
 
-### `typed(tokens)`
+### `typed(tokens, kind?)`
 
 Exactly one value token holding a finite number, a boolean, or a valid `Date` keeps that
 pre-stringify value. Anything else, including a lone null, reports `undefined` and joins to
-display text. Spreadsheet consumers use this for real numeric cells;
+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;
 [`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
 
 ### `walk(events, handlers)` / `breathe()`
@@ -132,6 +138,24 @@ itself.
 `breathe()` is that hand-back alone. Await it between batches of a loop you own; `walk` already
 calls it for you.
 
+### Presentation helpers
+
+A target that stringifies imports these rather than restating them, so every surface presents a
+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()`.
+- `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.
+- `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.
+
 ### `validate(schema, functions?)`
 
 Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
@@ -172,7 +196,7 @@ query budget failures) `limit` and `actual`.
 
 ```js
 try {
-  await renderer(data);
+  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