quario 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # quario
 
+## 0.11.0
+
+### Minor Changes
+
+- **`isBoxName(name)` is exported.** It answers whether a style name is part of the box — a padding or a border part — which is the partition the spec defines a table row's box by. A target that strips the box off a style, or a tool that lists the box names, imports it beside `STYLE_NAMES` rather than matching the two prefixes itself.
+- **A number kind reads `negative` and `zero`.** `format` gains two modifiers on `number`, `currency` and `percent`: `negative` is `"minus"` or `"parens"`, and `zero` is `"number"` or `"dash"`. Under `parens` a negative reads as its magnitude in parentheses, and under `dash` a zero reads as `-`. Both defaults are what every kind presented before, so no existing report moves. They compose with `digits`, with the percent kind's scaling and with a currency's code. A value outside either pair is a located definition error, and `date` takes neither. The resolved declaration a cell carries now states all three of a number kind's modifiers, so no consumer defaults one for itself.
+- **A group may declare `collapsed`.** One optional literal, `true` or `false`, asking that the instance open **shut**: its header and footer are shown and the content between them is not. Aggregates are untouched — the rows stay in the partition and still count, so a footer totals what nobody is shown. The `group-start` event carries it, and the new `collapse(stream)` helper is what a target with nowhere to hide a row reads the stream through: it drops a collapsed instance's content, nested instances whole, and keeps its brackets and its own bands. An expression is a located definition error.
+- **A group may declare a `label`.** One optional template beside `name` and `by`, resolved once per instance in group scope — the instance's own handle and `$` are bound, `@` is unbound as in any group band — and carried on `group-start` as the resolved text. It names the instance for navigation rather than for the page: a target with somewhere to put a navigation name spends it there, and the others withdraw it, so no page changes. A value that is not a template string is a located definition error, and a hollow instance stays unlisted whether it declares one or not.
+- **A run may carry an `href`.** The twelfth name in the styled run's inline subset, and the one declaration this engine judges rather than passes on: a URL names a location, and `javascript:` is a string-to-code path that escaping at the markup edge cannot answer. A URL is admitted before it crosses, against a host allowlist — `quario({ schemes })`, defaulting to `https:` and `mailto:` — so a target receives a URL already admitted or none at all. A refused value is omitted, so the text renders and the link does not; a URL stating no scheme is refused with the rest, because a scheme list cannot say "no scheme" without admitting `//host/path`. An `href` beginning `#` names a group's `label` and needs no allowlist. A `schemes` option the engine cannot read throws at construction rather than falling back to the default, because an allowlist quietly replaced is a host believing it restricted something it had not. A table row refuses `href`, as it refuses every declaration that presents a value.
+- **`REPORT_STYLE_NAMES`.** The two names a report default may declare, `family` and `size`, in the vocabulary's own order — the same export `RUN_STYLE_NAMES` already is, so a tool that offers them reads the engine rather than keeping a copy.
+- **A document may mark a declaration `required`, and `plan` checks it against the targets you name.** `"required": { "uppercase": true }` at the report root says which declarations this document cannot do without; `plan(schema, funcs, { targets })` takes the `capabilities` descriptors of the targets it is meant for, and every required declaration one of them withdraws or leaves unread becomes a problem of its own at `required.<name>`, which nulls the report as any other problem does. An approximated declaration is not one. Every withdrawal was silent by design before this, so this is how an author says that one of them matters. Additive throughout: no target sees the marking, no render changes because of it, and passing no descriptors checks nothing. A name outside the set the support matrix answers for is a definition error, because a marking nothing can check would go quiet exactly when it was needed. `REQUIRABLE` exports that set.
+
+### Patch Changes
+
+- **The declarations now state every `format` modifier the engine settles.** `FormatDeclaration` and `ResolvedFormat` carry `negative` and `zero` beside `digits` and `form`, and `FORMAT_VOCABULARY` offers the two readings and their defaults — `negatives`, `zeroes`, `defaultNegative`, `defaultZero` — with `modifiers` naming every modifier a kind takes rather than one of them. The engine has always read and resolved those declarations; the types said otherwise, so a TypeScript consumer writing one was told it was an error, and a tool reading the vocabulary to offer them found only the count.
+- **An error quario replaces keeps the one it replaced, as `cause`.** A failure inside one of your own functions reaches you named where it happened — `detail[0].value [{{ total() }}]: ...` — which is a copy, rebuilt from the class and a prefixed message. The stack that says which line of your function threw used to go with the original. It now rides along: read `error.cause` for the throw as it happened, and the message for where quario was when it happened.
+
+  The viewer's and the editor's own property checks do the same. A `page` or `fonts` value either element refuses throws a `TypeError` naming the property, and that error now carries the layout's own account of the value behind it.
+
+- **An all-authored split whose slot widths sum under 100 warns, as a table's columns already did.** A split's slots carry the same percentage shares under the same arithmetic, so the plan now reports the trailing width they leave unused, on the split's `slots` path. The report still renders; the warning is advisory, like every other.
+
+## 0.10.0
+
+### Minor Changes
+
+- **A group's `break` names a position, and `break: "page"` is retired.** Its values are `"before"`, `"between"`, `"after"` and `"around"`. Write `break: "before"` where you wrote `break: "page"`. That is the whole of the migration, and it changes nothing the report produces.
+
+  The boundary between two consecutive instances always turns a page. `before` adds the leading edge of the run, so the first instance opens a page of its own. `between` adds neither edge, which keeps the first instance on the page the report header opened — the case the old vocabulary could not express, and the reason for the change. `after` adds the trailing edge, and `around` adds both. A trailing edge turns the page for what follows the run, so a report whose last band is that group reads `after` as `between` and `around` as `before`. A nested group takes its two edges from each instance of the group above it, rather than from the document. `"page"` said which unit a break used, where the four say where it falls; one set cannot say both and still read at a glance.
+
+  **`reset: "page"` turns no page of its own, and now needs a `break` beside it.** It says only that a new `page.number` / `page.total` sequence starts at this instance. A sequence owns whole pages, so `reset` requires `break` to be `"before"` or `"around"`. Any other `break`, and `reset` with no `break` at all, is a definition error the compile reports. Add `break: "before"` to a group that declares `reset` alone today.
+
+  The HTML target adds `q-break` to an instance whose leading edge turns, as before, and the new `q-break-after` to one whose trailing edge turns. `@quario/html/style.css` gains `.q-break-after { break-after: page }` beside the rule it already shipped for `.q-break`.
+
+  The Word target also stops losing a page break a table would swallow. A table carries no paragraph properties, so a break owed where one starts had nowhere to sit and reached the next paragraph instead, on the wrong page or on none. It now gets a paragraph of its own, the same carrier a section break already took.
+
+  The render-event stream states the two edges rather than the four positions. `group-start` carries `break` where a page turns before the instance, and the new `breakAfter` where one turns after it, so a target reads boundaries and never the position that asked for them.
+
+- **Two new reducers: `first` and `last`.** They report the value an expression takes on the first and the last row in scope. Like every reducer, each one arrives on three surfaces at once: a declared aggregate on a report or a group, a runner under `run`, and a function you can call inline over a row's own array.
+
+  ```jsonc
+  // the customer a region's rows open and close on
+  { "aggregates": { "opened": "first:=@.customer", "closed": "last:=@.customer" } }
+  ```
+
+  ```
+  {{ first(@.lines, l => l.sku) }}   the first line's article number
+  ```
+
+  They are the first reducers that read the **order** of the rows they fold, so the spec now says what each scope hands them. Every scope reports the ends of the rows it folded, which is not always what the page ends on. A report folds after `where`, its `sort` and its `take`, and before it splits the rows into groups. A group that declares a `sort` and no `take` folds its partition before it orders that partition, so its handle holds the partition's ends. Declare `first` under a group's `run` when a detail row needs the row that group opens on as rendered.
+
+  An empty scope gives `null` for both, next to `avg`, `min` and `max`. Neither reducer skips a null: a scope whose first row holds `null` reports that `null`.
+
+  Reports that already render are unaffected. A document that spelled `first:=...` before was a definition error, and it now compiles.
+
+- **A hollow instance's `group-end` carries `hollow: true`.** An instance whose bands emitted nothing between its two brackets is hollow, and a hollow instance is not there: no space, no gap, no page turned by opening one, no outline entry. The stream now says which instances those are, on the closing bracket, so a target reads one field rather than counting the events between the brackets for itself. An instance holding nothing but hollow instances is hollow too, and one holding a child that drew is not. The field is absent, never `false`, on an instance that drew.
+
+  `@quario/layout`, and through it `@quario/pdf`, the viewer and the editor, read the field and keep no tracker of their own. What they render is unchanged.
+
+- **`splits(events)` folds a split bracket into one event.** A split reaches the event stream as `split-start`, one `item` or `image` per slot, then `split-end`, and every consumer that wanted a split whole kept that bracket for itself. `splits` does it once: read `walk(splits(events), handlers)` and register a `split` handler, which receives the opening event's `role`, `path`, `slots` and `style` plus the slot events in order under `items`. Every other event passes through unchanged, lazily.
+
+  The stream itself is unchanged. A consumer that registers no `split-start` handler still receives the slots as ordinary events and stacks them, as before. The `SplitStartEvent` declaration now names its `path`, which the stream always carried.
+
+  Every built-in target reads its splits this way now, so a custom target can too.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -11,6 +11,18 @@ The engine does not escape text, emit HTML, or format pages or cells. Install a
 want output. Use this package when you want to _build_ a target, or to consume report structure
 as data.
 
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API](#api)
+- [The scope model](#the-scope-model)
+- [Options](#options)
+- [Writing a render target](#writing-a-render-target)
+- [Content Security Policy](#content-security-policy)
+- [Documentation](#documentation)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -90,7 +102,7 @@ row, one `total-row` per emitted total row, and `table-end`.
 | `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-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `breakAfter`, `reset`, `columns`                                                                                                                    |
 | `group-end`    | `name`, `depth`                                                                                                                                                                                                     |
 | `table-start`  | `path`, `header` (`cells`, optional `style`), `columns` (each an optional `width`)                                                                                                                                  |
 | `row`          | `cells`, optional `style`, `run`                                                                                                                                                                                    |
@@ -155,6 +167,14 @@ itself.
 `breathe()` is that return alone. Await it between batches of a loop you own. `walk` already
 calls it for you.
 
+### `splits(events)`
+
+A split reaches the stream as a bracket: `split-start`, one `item` or `image` per slot, `split-end`.
+`splits` folds each bracket into one `split` event that carries the opening's fields and the slot
+events under `items`, and passes every other event through, lazily. Read `walk(splits(events),
+handlers)` and register a `split` handler where you want a split whole, and keep no bracket state of
+your own. Every official target reads its splits this way.
+
 ### Presentation helpers
 
 A target that stringifies imports these rather than restating them, so every surface presents a
@@ -173,6 +193,8 @@ cell the same way:
   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.
+- `isBoxName(name)` — whether a style name is part of the box, a padding or a border part. The
+  spec defines a row's box by this partition, and this function is its one home.
 
 ### `validate(schema, functions?)`
 
@@ -187,7 +209,7 @@ validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
 `report()` throws on the first problem instead. Validation and compilation share one traversal,
 so `validate()` can never disagree with what `report()` accepts.
 
-### `quario().plan(schema, functions?)`
+### `quario().plan(schema, functions?, { targets }?)`
 
 The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns
 `{ report, problems, anchors, warnings }`: the compiled report (`null` while the document has
@@ -206,6 +228,21 @@ a cell whose `format` is not `"currency"`, and a table where the author sized ev
 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.
 
+**`targets` checks the document against where it is going.** A document may mark declarations it
+cannot do without — `"required": { "uppercase": true }` at its root — and hand `plan` the
+`capabilities` descriptors of the targets it is meant for. Each required declaration one of them
+withdraws, or leaves unread as the page bands are, becomes a problem of its own at
+`required.<name>`, which nulls the report as any other problem does. An approximated one does not:
+the target rendered the intent as closely as it can. Pass no descriptors and nothing is checked,
+which is what keeps the marking additive. It is never a render-time failure.
+
+```js
+import { capabilities as csv } from "@quario/csv";
+
+const { problems } = quario().plan(schema, undefined, { targets: [csv] });
+// required.uppercase: the csv target withdraws "uppercase"
+```
+
 ```js
 const { report, problems, anchors, warnings } = quario().plan(schema);
 for (const warning of warnings) console.warn(warning.message);
@@ -261,7 +298,7 @@ carry `code`, `limit`, and `actual`. Every render starts with fresh counters.
 ## Writing a render target
 
 Read the stream through the public API. Do not reach for engine internals. A complete, tested
-Markdown target lives in the repository at `example/markdown.js` in about 70 lines. The built-in
+Markdown target lives in the repository at `example/markdown.js` in under 60 lines of code. The built-in
 targets use the same public API.
 
 Two rules a target owes its users: escape or neutralize every `value` token at your own edge, and

package/lib/band-height.js

@@ -12,13 +12,11 @@
  * 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").
+ * of the schema: `plan.js` offers it each band as it compiles it, so a fault
+ * lands in the documented key order beside every other problem.
  */
 
-import { isExpr, positivePts } from "./style.js";
+import { positivePts } from "./style.js";
 
 /**
  * A lead: authored flow spacing before an item that a target would actually
@@ -45,55 +43,46 @@ export let LEAD_REFUSED = "must be 0 after a height-declared header";
  */
 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.
+ * Whether an item's occupancy is the data's to decide is `optional`'s answer,
+ * which the item compilers own: this file knows what a lead is and which node
+ * a fault names, not which item kinds can decline to render.
  *
- * @type {(list: any, path: string) => { def: any, path: string } | undefined | null}
+ * @type {(optional: (def: any) => boolean, list: any, path: string) => { def: any, path: string } | undefined | null}
  */
-let firstOccupying = (list, path) => {
+let firstOccupying = (optional, 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 + "]" };
+  return optional(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.
+ * partly the data's. With rows, every group level opens before any detail
+ * row, so the first group header carrying an occupying item is that band —
+ * the order `bandOf` compiles them in, so `body` takes the first band that
+ * says anything. With no rows the `empty` band replaces all of it, judged on
+ * its own by `instead`. Both outcomes are reachable for any report declaring
+ * both, 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.
+ * A table `detail` reaches neither and needs no case: `table-start` and `row`
+ * are not occupying events, and the style vocabulary refuses `spaceBefore` on
+ * a table, a row and a cell alike.
  *
  * @param {(path: string, message: string) => void} bad The traversal's collector.
+ * @param {(def: any) => boolean} optional Whether an item definition may
+ *   decline to occupy at render — the item compilers' verdict, so a new item
+ *   kind that can states it where it is compiled rather than here.
  * @returns {{ arm: (height: number | null) => void,
  *   instead: (list: any, path: string) => void,
  *   body: (list: any, path: string) => void }} The guard.
  */
-export let pinGuard = (bad) => {
+export let pinGuard = (bad, optional) => {
   let pinned = false;
   let settled = true;
   /** @type {(found: { def: any, path: string } | undefined | null) => void} */
@@ -106,11 +95,11 @@ export let pinGuard = (bad) => {
       settled = !pinned;
     },
     instead: (/** @type {any} */ list, /** @type {string} */ path) => {
-      if (pinned) refuse(firstOccupying(list, path));
+      if (pinned) refuse(firstOccupying(optional, list, path));
     },
     body: (/** @type {any} */ list, /** @type {string} */ path) => {
       if (settled) return;
-      let found = firstOccupying(list, path);
+      let found = firstOccupying(optional, 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

package/lib/format.js

@@ -11,14 +11,12 @@
  * 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()`.
+ * declaration `formatOf` answers — the same object 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).
  */
 import { boundedMemo } from "./memo.js";
-import { currencyOf, formatOf } from "./style.js";
+import { ZERO_DASH, currencyOf, formatOf } from "./style.js";
 import { finiteDate, finiteNum, reviveDate } from "./stream.js";
 /** @type {(options: any) => string} */
 let localeOf = (options) => options?.locale || "en-US";
@@ -29,29 +27,23 @@ let zoneOf = (options) => options?.timeZone || "UTC";
 // 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 key is everything the formatter is made from**, by value rather than
+// 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 `=` resolves a fresh one per cell. Get a piece wrong and one
+// cell presents under another's formatter — a USD row reading as EUR — which
+// `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.
 //
 // **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.
+// can be an `=` result too: 17,576 codes times 21 counts is 369,000 keys for
+// one locale, about 90 MB at 244 bytes retained per entry.
 //
-// 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.
+// 2048 is about 500 KB at the cap, against a real report reaching a small
+// multiple of the ISO codes in circulation. Neither bound is a correctness
+// knob.
 //
 // Memoising a fact that cannot change within an ICU version, like
 // `fractionDigits`' own minor-units map (docs/adr/0025).
@@ -122,6 +114,34 @@ let asDate = (value, locale, decl, options) => {
 /** @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 two presentation modifiers a number kind carries, applied around
+// whatever its own formatter produced. A `date` carries neither, and answers
+// `undefined` to both reads below.
+//
+// Parentheses are spelled here rather than taken from Intl's accounting sign:
+// the worksheet writes the same negative section into its number format, and
+// the two edges have to agree on one wording (docs/adr/0056, as amended).
+// Which is also why the number is formatted from its own magnitude — the sign
+// a locale would have written is exactly what the parentheses replace.
+/** @type {(value: any, decl: any) => any} */
+let magnitude = (value, decl) =>
+  decl.negative === "parens" && finiteNum(value) && value < 0 ? -value : value;
+// What each sign reads as, given the modifiers its kind carries. A table
+// rather than a chain, so the three cases are three entries and each one is
+// the whole answer for its sign.
+/** @type {Record<string, (text: string, decl: any) => string>} */
+let SIGNED = {
+  zero: (text, decl) => (decl.zero === "dash" ? ZERO_DASH : text),
+  negative: (text, decl) => (decl.negative === "parens" ? "(" + text + ")" : text),
+  positive: (text) => text,
+};
+// `value === 0` is true of a negative zero, which is a zero.
+/** @type {(value: number) => string} */
+let signOf = (value) => (value === 0 ? "zero" : value < 0 ? "negative" : "positive");
+/** @type {(value: any, text: string | undefined, decl: any) => string | undefined} */
+let presented = (value, text, decl) =>
+  text === undefined || !finiteNum(value) ? text : SIGNED[signOf(value)](text, decl);
+
 /**
  * The helper takes the whole resolved `style`, not just the declaration, so
  * the question "which declarations does presentation read?" is answered here
@@ -145,7 +165,8 @@ export function format(value, style, options) {
   let decl = formatOf(style, options);
   if (!decl) return;
   try {
-    return KINDS[decl.kind](value, localeOf(options), decl, options, style);
+    let text = KINDS[decl.kind](magnitude(value, decl), localeOf(options), decl, options, style);
+    return presented(value, text, decl);
   } catch {
     return;
   }

package/lib/index.d.ts

@@ -125,6 +125,28 @@ export interface SortKey {
  */
 export const RUN_STYLE_NAMES: readonly string[];
 
+/**
+ * The names a [report default](../../../SCHEMA.md#style-declarations) may
+ * declare, in the vocabulary's own order. A tool that offers them — the
+ * editor's Document panel — reads this rather than keeping a copy.
+ */
+export const REPORT_STYLE_NAMES: readonly string[];
+
+/**
+ * What a cell reads as under `format`'s `zero: "dash"`. Stated once, because
+ * the XLSX target writes the same character into its sectioned number format
+ * and the two edges must agree.
+ */
+export const ZERO_DASH: string;
+
+/**
+ * The declarations a document may mark [`required`](../../../SCHEMA.md#validation),
+ * in the order the support matrix states them. Every published target's
+ * `capabilities` descriptor answers for exactly these, which is what makes a
+ * marking checkable.
+ */
+export const REQUIRABLE: readonly string[];
+
 /**
  * The declarations a styled run accepts: the inline half of the vocabulary,
  * and nothing else. The box and flow spacing describe a block and `align`
@@ -173,26 +195,42 @@ export type FormatKind = "number" | "currency" | "percent" | "date";
  * none is `"medium"`. */
 export type DateForm = "short" | "medium" | "long" | "full";
 
+/** How a negative amount reads. A number kind that names none is `"minus"`. */
+export type NegativeReading = "minus" | "parens";
+
+/** How a zero reads. A number kind that names none is `"number"`. */
+export type ZeroReading = "number" | "dash";
+
 /**
- * How an author writes `format`: the kind alone, or the kind carrying its one
- * modifier. `digits` is a whole number from 0 to 20 — the range both a
- * presenting target and a worksheet number format can honour — and it beats
+ * How an author writes `format`: the kind alone, or the kind carrying the
+ * modifiers it takes. `digits` is a whole number from 0 to 20 — the range both
+ * a presenting target and a worksheet number format can honour — and it beats
  * the count the kind would otherwise present, a currency's minor units
  * included. A modifier on a kind that does not take it is a definition error.
  */
 export type FormatDeclaration =
   | FormatKind
-  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | {
+      kind: "number" | "currency" | "percent";
+      digits?: number;
+      negative?: NegativeReading;
+      zero?: ZeroReading;
+    }
   | { kind: "date"; form?: DateForm };
 
 /**
  * What `format` resolves to on the event stream: never the shorthand, always
  * the kind with the answer it presents. A number kind carries `digits` unless
- * it has no count at all — a `currency` whose code cannot be read — and a
- * `date` always carries its `form`.
+ * it has no count at all — a `currency` whose code cannot be read — and both
+ * of its readings, and a `date` always carries its `form`.
  */
 export type ResolvedFormat =
-  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | {
+      kind: "number" | "currency" | "percent";
+      digits?: number;
+      negative: NegativeReading;
+      zero: ZeroReading;
+    }
   | { kind: "date"; form: DateForm };
 
 export interface Cell {
@@ -367,11 +405,15 @@ export interface TableDetail {
 export interface Group {
   name: string;
   by: `=${string}`;
-  /** Start every instance of this group on a new page (paginated targets). */
-  break?: "page";
   /**
-   * Restart `page.number` / `page.total` at every instance. Each instance also
-   * starts on a fresh page, the same rule `break` has.
+   * Where this group turns a page (paginated targets). Every boundary between
+   * consecutive instances turns; `before` adds the run's leading edge, `after`
+   * its trailing edge, and `around` both.
+   */
+  break?: "before" | "between" | "after" | "around";
+  /**
+   * Restart `page.number` / `page.total` at every instance. It turns no page
+   * of its own, so it requires `break` to be `"before"` or `"around"`.
    */
   reset?: "page";
   /**
@@ -664,6 +706,8 @@ export interface ImageEvent {
 export interface SplitStartEvent {
   type: "split-start";
   role: ItemRole;
+  /** The split definition's schema path. */
+  path: string;
   /** One entry per slot, in order; `width` is absent on a width-less slot. */
   slots: { width?: number }[];
   style?: Record<string, unknown>;
@@ -673,6 +717,15 @@ export interface SplitEndEvent {
   type: "split-end";
 }
 
+/**
+ * A split bracket folded whole by `splits()`: the opening event's fields, and
+ * the slot events in slot order under `items`. No stream emits it.
+ */
+export interface SplitEvent extends Omit<SplitStartEvent, "type"> {
+  type: "split";
+  items: (ItemEvent | ImageEvent)[];
+}
+
 export interface GroupStartEvent {
   type: "group-start";
   name: string;
@@ -681,17 +734,29 @@ export interface GroupStartEvent {
   depth: number;
   key: unknown;
   aggregates: Record<string, unknown>;
+  /** The instance's navigation name, resolved from the group's `label` and
+   *  joined to text. Absent where the group declares none, so a target with a
+   *  name it derives keeps deriving it. */
+  label?: string;
+  /** A page turns before this instance, resolved from the group's `break`. */
   break?: "page";
+  /** A page turns after this instance, resolved from the group's `break`. */
+  breakAfter?: "page";
   /** Restart `page.number` / `page.total` at every instance (paginated targets). */
   reset?: "page";
   /** The declared page column count, present when the group declares one. */
   columns?: number;
+  /** The instance opens shut, present only when the group declares it: its
+   *  bands are shown and the content between them is not. */
+  collapsed?: true;
 }
 
 export interface GroupEndEvent {
   type: "group-end";
   name: string;
   depth: number;
+  /** Present when the instance is hollow: nothing but group brackets arrived between its ends. */
+  hollow?: true;
 }
 
 export interface TableStartEvent {
@@ -766,9 +831,33 @@ export interface ReportEventStream {
  * ignores that event.
  */
 export type WalkHandlers = {
-  [K in ReportEvent["type"]]?: (event: Extract<ReportEvent, { type: K }>) => void;
+  [K in WalkEvent["type"]]?: (event: Extract<WalkEvent, { type: K }>) => void;
 };
 
+/** What the walk driver dispatches: a stream event, or a split `splits()` folded. */
+export type WalkEvent = ReportEvent | SplitEvent;
+
+/**
+ * The split bracket folded: every `split-start`, its slot events and its
+ * `split-end` become one `split` event, and every other event passes through
+ * untouched, lazily. Read `splits(stream)` where a split is wanted whole rather
+ * than keeping a bracket of your own; register a `split` handler and no
+ * `split-start` or `split-end` one.
+ */
+export function splits(events: Iterable<ReportEvent>): Generator<WalkEvent, void>;
+
+/**
+ * Each [collapsed](../../../SCHEMA.md#group-definition) instance shut: its
+ * brackets and its own header and footer items survive, and everything
+ * between them is dropped, nested instances whole.
+ *
+ * For a target with no way to hide a row and keep it. One that has — the
+ * worksheet — reads the stream as it is. Aggregates are untouched either
+ * way. Read it over `splits(stream)`, so a split inside a header arrives
+ * folded and wearing the role this reads.
+ */
+export function collapse(events: Iterable<WalkEvent>): Generator<WalkEvent, void>;
+
 /**
  * The walk driver: dispatch one render's event stream to per-event handlers,
  * in stream order and exactly once each, pulling lazily and handing the loop
@@ -778,7 +867,7 @@ export type WalkHandlers = {
  * than pulling the stream itself; no opening event is required, and a stream
  * that starts part-way through walks like any other.
  */
-export function walk(events: Iterable<ReportEvent>, handlers: WalkHandlers): Promise<void>;
+export function walk(events: Iterable<WalkEvent>, handlers: WalkHandlers): Promise<void>;
 
 /**
  * Hand the event loop back to the host, resolving once it has had its turn.
@@ -865,6 +954,27 @@ export interface Warning {
  * complement of `names`, which excludes them. `problems` is fatal and
  * `warnings` is advisory, both in document order from the one descent.
  */
+/** A target's `capabilities` descriptor, as each published target exports it. */
+export interface TargetCapabilities {
+  readonly target: string;
+  readonly declarations: Readonly<Record<string, string>>;
+}
+
+/** What a caller asks `plan` to check beyond the document itself. */
+export interface PlanOptions {
+  /**
+   * The `capabilities` descriptors of the targets this document is meant for.
+   * Every declaration the document marks `required` that one of them
+   * withdraws or leaves unread becomes a problem of its own, which nulls the
+   * report exactly as any other problem does. Omit them and nothing is
+   * checked, which is what makes the marking additive.
+   *
+   * Descriptors rather than targets: the engine knows about no target, and
+   * what it reads here is the data a target ships about itself.
+   */
+  readonly targets?: readonly TargetCapabilities[];
+}
+
 export interface Plan {
   readonly report: CompiledReport | null;
   readonly problems: readonly Problem[];
@@ -885,7 +995,7 @@ export interface Quario {
    * problems, advisory warnings, and per-node anchor sets — one descent per
    * edit for a host that validates and renders in a loop.
    */
-  plan(schema: unknown, functions?: FunctionRegistry): Plan;
+  plan(schema: unknown, functions?: FunctionRegistry, options?: PlanOptions): Plan;
 }
 
 /**
@@ -1037,6 +1147,14 @@ export function isReportBand(role: string | undefined): boolean;
  */
 export const STYLE_NAMES: readonly string[];
 
+/**
+ * Whether a style name belongs to the box: a padding or a border part. The
+ * partition is the spec's (a row's box is defined by it), and this is its one
+ * home. A target that strips the box off a style, or a tool that lists the box
+ * names, asks this rather than matching the prefixes itself.
+ */
+export function isBoxName(name: string): boolean;
+
 /**
  * The `format` vocabulary as data, for a tool that offers it rather than
  * checks it — a style rail's kind picker and its modifier control — so no
@@ -1045,9 +1163,14 @@ export const STYLE_NAMES: readonly string[];
 export const FORMAT_VOCABULARY: {
   readonly kinds: readonly FormatKind[];
   readonly forms: readonly DateForm[];
-  /** Which modifier each kind takes, so a surface offering the pair need not
-   * know that three kinds share `digits` and `date` does not. */
-  readonly modifiers: Readonly<Record<FormatKind, "digits" | "form">>;
+  readonly negatives: readonly NegativeReading[];
+  readonly zeroes: readonly ZeroReading[];
+  /** Which modifiers each kind takes, in the order a surface offers them, so
+   * one offering them need not know that three kinds share theirs and `date`
+   * does not. */
+  readonly modifiers: Readonly<Record<FormatKind, readonly string[]>>;
   readonly defaultForm: DateForm;
+  readonly defaultNegative: NegativeReading;
+  readonly defaultZero: ZeroReading;
   readonly maxDigits: number;
 };