quario 0.5.0 → 0.7.0

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,21 +110,31 @@ 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.
 
+### `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
@@ -132,6 +146,25 @@ 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, and
+  `RUN_STYLE_NAMES` — the inline half of it, which is what a styled run may wear.
+
 ### `validate(schema, functions?)`
 
 Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
@@ -148,34 +181,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 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
+  // 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;
 }
 ```
 

package/lib/band-height.js

@@ -0,0 +1,123 @@
+/**
+ * The band-height rule: what a report header's declared `height` forbids of
+ * whatever follows its box (docs/adr/0038, docs/adr/0052).
+ *
+ * A pinned header ends at a fixed offset from the page top, so the band under
+ * it starts there and an authored lead would push it off the pin. The rule is
+ * therefore about one item — the first occupying item of the band that follows
+ * — and it is enforced twice, because which item that is can be a fact about
+ * the document or a fact about the render. `plan.js` refuses the ones the
+ * document settles; `index.js` refuses the rest as the stream produces them.
+ * Both read this file, so the two never disagree about what a lead is or which
+ * node a fault names.
+ *
+ * The traversal half is a guard the descent carries rather than a second walk
+ * of the schema: `plan.js` offers it each band as it compiles it, in the order
+ * it already visits them, so a fault lands in the documented key order beside
+ * every other problem and the group chain is read once
+ * (docs/agents/semantics.md, "One traversal, read two ways").
+ */
+
+import { isExpr, positivePts } from "./style.js";
+
+/**
+ * A lead: authored flow spacing before an item that a target would actually
+ * paint. A positive number of points — the style vocabulary's own shape, less
+ * the zero it admits, which is the value the pin asks for. `spaceOf` in
+ * @quario/layout applies the same test; @quario/html's `isPad` is deliberately
+ * wider, admitting the `0` that is harmless to emit as CSS. They are restated
+ * per package on purpose: the engine is their peer dependency, so it cannot
+ * import either.
+ *
+ * @type {(n: any) => boolean}
+ */
+export let isLead = positivePts;
+
+/** The one wording, so both enforcement sites report the same sentence. */
+export let LEAD_REFUSED = "must be 0 after a height-declared header";
+
+/**
+ * The path of the key a lead fault names: the offending item's own
+ * `style.spaceBefore`.
+ *
+ * @param {string} path The item definition's schema path.
+ * @returns {string} The located key.
+ */
+export let leadPath = (path) => path + ".style.spaceBefore";
+
+/**
+ * An occupancy the document leaves to the data: a `visible` written as an
+ * expression, or an image, whose bytes are expression-only and whose event is
+ * absent when its `source` yields nothing (SCHEMA.md, "Event stream"). Neither
+ * is a defect — they are how an author writes an optional item — but they mean
+ * the traversal cannot say which item comes first, so it says nothing rather
+ * than guessing (docs/adr/0052).
+ *
+ * @type {(def: any) => boolean}
+ */
+let dataDecides = (def) => isExpr(def?.visible) || def?.type === "image";
+
+/**
+ * The first item of a band the document settles as occupying, `undefined` when
+ * only the render settles it, and null for a band settled to occupy nothing.
+ *
+ * @type {(list: any, path: string) => { def: any, path: string } | undefined | null}
+ */
+let firstOccupying = (list, path) => {
+  if (!Array.isArray(list)) return null;
+  let i = list.findIndex((def) => def?.visible !== false);
+  if (i < 0) return null;
+  return dataDecides(list[i]) ? undefined : { def: list[i], path: path + "[" + i + "]" };
+};
+
+/**
+ * The guard the traversal carries while it descends.
+ *
+ * Which band sits under the pinned box is partly the document's answer and
+ * partly the data's. With rows, every group level opens nested before any
+ * detail row, so the first group header carrying an occupying item is that
+ * band, and `detail` is it only when no group header has one — which is the
+ * order `bandOf` already compiles them in, so `body` takes the first band that
+ * says anything and ignores the rest. With no rows the `empty` band replaces
+ * all of it, so it is an independent candidate that `instead` judges on its
+ * own. Both outcomes are reachable for any report declaring both, and the
+ * author declared each, so a lead on either is refused.
+ *
+ * A table `detail` reaches neither, and needs no case of its own:
+ * `table-start` and `row` are not occupying events, and the style vocabulary
+ * refuses `spaceBefore` on a table, a table row and a table cell alike, so
+ * there is no lead a table could carry.
+ *
+ * @param {(path: string, message: string) => void} bad The traversal's collector.
+ * @returns {{ arm: (height: number | null) => void,
+ *   instead: (list: any, path: string) => void,
+ *   body: (list: any, path: string) => void }} The guard.
+ */
+export let pinGuard = (bad) => {
+  let pinned = false;
+  let settled = true;
+  /** @type {(found: { def: any, path: string } | undefined | null) => void} */
+  let refuse = (found) => {
+    if (found && isLead(found.def.style?.spaceBefore)) bad(leadPath(found.path), LEAD_REFUSED);
+  };
+  return {
+    arm: (/** @type {number | null} */ height) => {
+      pinned = height != null;
+      settled = !pinned;
+    },
+    instead: (/** @type {any} */ list, /** @type {string} */ path) => {
+      if (pinned) refuse(firstOccupying(list, path));
+    },
+    body: (/** @type {any} */ list, /** @type {string} */ path) => {
+      if (settled) return;
+      let found = firstOccupying(list, path);
+      // A band settled to occupy nothing is not the one under the box, so the
+      // descent keeps looking; one only the render settles ends the search
+      // without a verdict, because whether the band below is next is exactly
+      // what it left open.
+      if (found === null) return;
+      settled = true;
+      refuse(found);
+    },
+  };
+};

package/lib/format.js

@@ -1,66 +1,151 @@
 /**
  * Present a cell's raw token as `number` / `currency` / `percent` / `date`.
- * Targets import this instead of each other: the stream keeps the kind on
- * `style` and the token raw, and HTML/PDF stringify at the edge. A kind on
- * the wrong type, or on null, contributes nothing — the caller falls back to
- * `display()`. Invalid locale or currency codes fail the same way.
+ * Targets import this instead of each other: the stream keeps the resolved
+ * declaration on `style` and the token raw, and HTML/PDF stringify at the
+ * edge. A kind on the wrong type, or on null, contributes nothing — the
+ * caller falls back to `display()`. Invalid locale or currency codes fail the
+ * same way. Under the `currency` kind a cell's own `style.currency` names the
+ * denomination and beats the instance's default code.
  *
  * Defaults (`en-US`, UTC) are pinned so a PDF without a host locale still
  * renders the same bytes on every machine (docs/adr/0041, docs/adr/0025).
+ *
+ * The kind, its digit count, and a date's form all come off the one resolved
+ * declaration `formatOf` answers — the same object the stream carries and the
+ * XLSX target builds its number formats from — so a cell shows the same
+ * digits wherever it is rendered (docs/adr/0054, docs/adr/0056). A kind that
+ * carries no count presents nothing here and the caller falls back to
+ * `display()`.
  */
+import { boundedMemo } from "./memo.js";
+import { currencyOf, formatOf } from "./style.js";
 import { finiteDate, finiteNum, reviveDate } from "./stream.js";
 /** @type {(options: any) => string} */
 let localeOf = (options) => options?.locale || "en-US";
 /** @type {(options: any) => string} */
 let zoneOf = (options) => options?.timeZone || "UTC";
 
-/** @type {(value: any, locale: string) => string | undefined} */
-let asNumber = (value, locale) =>
-  finiteNum(value) ? new Intl.NumberFormat(locale).format(value) : undefined;
-/** @type {(value: any, locale: string) => string | undefined} */
-let asPercent = (value, locale) =>
-  finiteNum(value) ? new Intl.NumberFormat(locale, { style: "percent" }).format(value) : undefined;
-/** @type {(options: any) => string | null} */
-let currencyOf = (options) => {
-  let currency = options?.currency;
-  return typeof currency === "string" && currency ? currency : null;
+// The formatters are memoised behind `./memo.js`'s bounded store, which
+// carries the rules a bounded memo has; what is here is what only this call
+// site knows -- its key, and its cap.
+//
+// **The key is everything the formatter is made from**, and it is values
+// rather than an object identity because no identity survives both paths: a
+// literal style block folds to one frozen declaration every cell shares, while
+// a block holding an `=` expression resolves a fresh one per cell (`plan.js`).
+// Keying on values hits in both. Get a piece of it wrong and one cell presents
+// under another's formatter -- a USD row reading as EUR -- which is the
+// failure `test/semantics.test.js` pins a pair for, one piece at a time. Each
+// pair must differ in **only** the piece it is there for: EUR against JPY
+// would prove nothing about the code, because their digit counts already
+// differ and that piece would separate them on its own.
+//
+// **The cap is the part to read**, because the key space is not the host's to
+// bound. A currency code reaches this from author data through
+// `currency: "=@.ccy"`, gated only to three uppercase letters, and `digits`
+// can be an `=` result too: 17,576 codes times 21 counts is 369,000 keys for a
+// single locale. Measured at 244 bytes retained per entry, that is about 90 MB
+// held for the life of the process on data nobody vetted.
+//
+// 2048 leaves the margin a threshold like this wants on both sides: about
+// 500 KB at the cap, against a real report reaching a small multiple of the
+// ISO codes actually in circulation, which is under two hundred. Raising it
+// costs bytes and lowering it costs rebuilt formatters; neither is a
+// correctness knob.
+//
+// Memoising a fact that cannot change within an ICU version, like
+// `fractionDigits`' own minor-units map (docs/adr/0025).
+let memo = boundedMemo(2048);
+
+// The kind leads, so a number's key can never read as a date's; the currency
+// is empty for the two kinds that wear none.
+/** @type {(locale: string, decl: any, rest?: any) => string} */
+let numberKey = (locale, decl, rest) =>
+  decl.kind + "|" + locale + "|" + decl.digits + "|" + (rest?.currency || "");
+
+/** @type {(value: any, locale: string, decl: any, rest?: any) => string | undefined} */
+let asFixed = (value, locale, decl, rest) => {
+  if (!finiteNum(value) || decl.digits === undefined) return;
+  return memo(
+    numberKey(locale, decl, rest),
+    () =>
+      new Intl.NumberFormat(locale, {
+        ...rest,
+        minimumFractionDigits: decl.digits,
+        maximumFractionDigits: decl.digits,
+      }),
+  ).format(value);
 };
-/** @type {(value: any, locale: string, options: any) => string | undefined} */
-let asMoney = (value, locale, options) => {
-  let currency = currencyOf(options);
-  if (!finiteNum(value) || !currency) return;
-  return new Intl.NumberFormat(locale, { style: "currency", currency }).format(value);
+
+/** @type {(value: any, locale: string, decl: any) => string | undefined} */
+let asNumber = (value, locale, decl) => asFixed(value, locale, decl);
+/** @type {(value: any, locale: string, decl: any) => string | undefined} */
+let asPercent = (value, locale, decl) =>
+  // `style: "percent"` multiplies by 100 and the digits count the *displayed*
+  // places, which is what Excel's `0.00%` already means too — so the count
+  // crosses to the sheet with no translation (docs/adr/0056).
+  asFixed(value, locale, decl, { style: "percent" });
+// The code the cell actually wears is what the digit count was asked about, not
+// the instance's: minor units are a property of the currency, so a row that
+// names JPY presents no decimals beside one naming EUR that presents two
+// (docs/adr/0041, docs/adr/0054).
+/** @type {(value: any, locale: string, decl: any, options: any, style: any) => string | undefined} */
+let asMoney = (value, locale, decl, options, style) => {
+  let currency = currencyOf(style, options);
+  return currency ? asFixed(value, locale, decl, { style: "currency", currency }) : undefined;
 };
 // A string in an accepted RFC 3339 form revives to the Date a host would have
 // injected, then presents like any other Date — including in the instance's
 // timezone, so a calendar date under a western zone presents as the day
 // before, exactly as an injected `new Date("2026-08-14")` does today. The two
 // spellings never disagree, which is the point (ADR 0041).
-/** @type {(value: any, locale: string, options: any) => string | undefined} */
-let asDate = (value, locale, options) => {
+//
+// The form is Intl's own `dateStyle`, and it is always present: a declaration
+// that named none resolved to `medium` (docs/adr/0056). This is the half that
+// does not converge — the worksheet approximates it (CONTEXT.md, "Form").
+// `date` leads for the same reason the number kinds do, so the two key shapes
+// live beside each other and "one piece at a time" is auditable in one place.
+/** @type {(locale: string, decl: any, zone: string) => string} */
+let dateKey = (locale, decl, zone) => "date|" + locale + "|" + decl.form + "|" + zone;
+
+/** @type {(value: any, locale: string, decl: any, options: any) => string | undefined} */
+let asDate = (value, locale, decl, options) => {
   let date = finiteDate(value) ? value : reviveDate(value);
-  return date
-    ? new Intl.DateTimeFormat(locale, { timeZone: zoneOf(options) }).format(date)
-    : undefined;
+  if (!date) return;
+  let zone = zoneOf(options);
+  return memo(
+    dateKey(locale, decl, zone),
+    () => new Intl.DateTimeFormat(locale, { timeZone: zone, dateStyle: decl.form }),
+  ).format(date);
 };
 
-/** @type {Record<string, (value: any, locale: string, options: any) => string | undefined>} */
+/** @type {Record<string, (value: any, locale: string, decl: any, options: any, style: any) => string | undefined>} */
 let KINDS = { number: asNumber, currency: asMoney, percent: asPercent, date: asDate };
 
 /**
+ * The helper takes the whole resolved `style`, not just the declaration, so
+ * the question "which declarations does presentation read?" is answered here
+ * once rather than once per target (docs/adr/0014).
+ *
  * @param {unknown} value The interpolation's pre-stringify token.
- * @param {unknown} kind A resolved `format` declaration.
+ * @param {{ format?: unknown, currency?: unknown } | null} [style] The cell's
+ *   resolved style block: its `format` declaration, and its own `currency`
+ *   code when it declares one.
  * @param {{ locale?: string, currency?: string, timeZone?: string } | null} [options]
- *   The instance's locale, currency code, and timezone.
+ *   The instance's locale, default currency code, and timezone.
  * @returns {string | undefined} The presented text, or nothing when this
  *   kind does not apply.
  */
-export function format(value, kind, options) {
-  if (typeof kind !== "string") return;
-  let present = KINDS[kind];
-  if (!present) return;
+export function format(value, style, options) {
+  // A style the stream resolved already carries its declaration whole; one a
+  // host built by hand may still hold the shorthand, so it is widened here
+  // rather than refused. No own-key guard on the lookup: `formatOf` answers a
+  // kind only from the closed vocabulary, which is exactly `KINDS`' own keys,
+  // so nothing an `=` expression resolved to can reach this table.
+  let decl = formatOf(style, options);
+  if (!decl) return;
   try {
-    return present(value, localeOf(options), options);
+    return KINDS[decl.kind](value, localeOf(options), decl, options, style);
   } catch {
     return;
   }