quario 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # quario
 
+## 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
+
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
+
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
+
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+### Patch Changes
+
+- The engine verifies a license key against a new signing key.
+
 ## 0.8.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
@@ -63,7 +75,7 @@ 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 synchronously from `render`, before the first event; definition problems
+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
@@ -80,7 +92,7 @@ report.paths; // padvinder's deeply frozen dependency topology for the `data` qu
 
 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
+content with `group-start`/`group-end`. A table detail yields `table-start`, one `row` per visible
 row, one `total-row` per emitted total row, and `table-end`.
 
 | Event          | Carries                                                                                                                                                                                                             |
@@ -88,9 +100,9 @@ row, one `total-row` per emitted total row, and `table-end`.
 | `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-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`                                                                                                                                                                                    |
@@ -108,18 +120,18 @@ a literal and a value, so the cell is text only.
 
 **A page-number token names itself.** A value token whose interpolation is exactly
 `{{ page.number }}` or `{{ page.total }}` also carries `field`, holding that same string. The
-value is the number this page was rendered with; `field` says which page value the token stands
+value is the number the render used for this page. `field` says which page value the token stands
 for, so a target whose own document format numbers pages can write its own live field there
 instead. Anything computed from them carries no `field`.
 
 **Escaping is the consumer's job.** A target that embeds values in markup must escape them at its
 own edge.
 
-**`report-start.marking`** carries the evaluation wording when the render is unlicensed, or while
-verification is still settling. Licensed streams omit it. Targets place the marking; they do not
+**`report-start.marking`** carries the evaluation wording when no license covers the render, 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](https://getquario.com/docs/diving-deeper/bands/#flowing-in-columns) count when
-present. `@quario/pdf` and `@quario/html` lay page columns out;
+present. `@quario/pdf` and `@quario/html` lay page columns out.
 xlsx never will.
 
 ### `text(tokens)`
@@ -133,7 +145,7 @@ Exactly one value token holding a finite number, a boolean, or a valid `Date` ke
 pre-stringify value. Anything else, including a lone null, reports `undefined` and joins to
 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;
+real numeric cells.
 [`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
 
 ### `styledRuns(tokens)`
@@ -147,14 +159,22 @@ 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
-per-event handlers keyed by type; a missing handler ignores that event. It pulls on demand, hands
-the loop back between batches, and delivers the opening event before pulling a second, so a
+per-event handlers keyed by type. A missing handler ignores that event. It pulls on demand,
+returns the loop between batches, and delivers the opening event before pulling a second, so a
 target can settle `report-start` (page bands, marking) there instead of draining the stream
 itself.
 
-`breathe()` is that hand-back alone. Await it between batches of a loop you own; `walk` already
+`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
@@ -163,11 +183,11 @@ 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()`.
+  declaration (its kind and modifier, and for `currency` the cell's own code). It answers
+  `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.
+  the declaration's `digits` overrides it. It answers `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.
@@ -176,8 +196,8 @@ cell the same way:
 
 ### `validate(schema, functions?)`
 
-Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
-empty array means valid.
+Validates a definition without rendering it. It returns every problem as a path-prefixed string.
+An empty array means valid.
 
 ```js
 validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
@@ -202,7 +222,7 @@ is not a problem at a lower severity, which is why it has no `diagnostic` — no
 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
+a cell whose `format` is not `"currency"`, and a table where the author sized every column 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.
 
@@ -217,10 +237,10 @@ else console.error(problems[0].path, problems[0].message);
 
 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.
+Authentication tests identity. An error that only matches the shape does not pass.
 
-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
+Location is not what the guard reads: quario's own verdicts on a document and a registered
+function's own throw carry a location 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
@@ -246,7 +266,7 @@ try {
 | `run.<name>`  | Running accumulator values on the current detail row                |
 
 Each anchor is a distinct object. Absent reads are `null`, so `x == null` holds for a missing
-field; reading _through_ a null base still throws, so use `?.`.
+field. Reading _through_ a null base still throws, so use `?.`.
 
 ## Options
 
@@ -254,15 +274,15 @@ field; reading _through_ a null base still throws, so use `?.`.
 quario({ query: { maxNodes: 10_000, maxDepth: 64, maxResults: 1_000 } }).report(schema, functions);
 ```
 
-`query` bounds the JSONPath data selection. Hosts set budgets through this API argument;
-definitions do not carry it. Failures are located at `data`, keep their `RangeError` type, and
+`query` bounds the JSONPath data selection. Hosts set budgets through this API argument.
+Definitions do not carry it. Failures point at `data`, keep their `RangeError` type, and
 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
-targets are written against the same public API.
+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
 map the [style vocabulary](https://getquario.com/docs/reference/style-declarations/) to your own
@@ -291,10 +311,10 @@ the [engine reference](https://getquario.com/docs/reference/quario/) is this pac
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key in the options; it is verified offline:
+Pass your license key in the options. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/band-height.js

@@ -12,10 +12,8 @@
  * 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";
@@ -74,19 +72,16 @@ let firstOccupying = (list, path) => {
  * 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.
  * @returns {{ arm: (height: number | null) => void,

package/lib/format.js

@@ -11,11 +11,9 @@
  * 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";
@@ -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).

package/lib/host.js

@@ -0,0 +1,89 @@
+/**
+ * What a host got wrong in a target factory's options, named. A target
+ * refuses what it does not understand at the factory call, so a typo costs
+ * one stack trace at the line the host wrote rather than a wrong document
+ * nothing reports (`docs/adr/0072`).
+ *
+ * Here rather than in a target for the reason `imageError` carries beside it:
+ * every target needs it, no two of them may depend on each other, and the
+ * engine is what they all already have. Nothing an author writes reaches this
+ * module -- these are host API, and no located diagnostic is involved.
+ */
+
+/** @type {(msg: string) => never} */
+let fail = (msg) => {
+  throw TypeError(msg);
+};
+
+/**
+ * An object a host may have written by hand: not an array, not a function, and
+ * not `null`, each of which is a different mistake wearing `typeof "object"`.
+ *
+ * @type {(value: unknown) => boolean}
+ */
+let plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// Own keys only: an inherited enumerable property is the prototype's business,
+// and naming it back at the host would name something they never wrote.
+/** @type {(value: object, keys: readonly string[], at: string) => void} */
+let closed = (value, keys, at) => {
+  for (let key of Object.keys(value))
+    if (!keys.includes(key)) fail(at + ': unknown option "' + key + '"');
+};
+
+/**
+ * A target's own options, with its key set closed. Nullish is absence, which
+ * is what the engine does with every value a host omits, so a host writing
+ * `meta: config.meta ?? null` is not a host making a mistake.
+ *
+ * @template T
+ * @param {T} value The options object, or a nested one.
+ * @param {readonly string[]} keys Every key this object may carry.
+ * @param {string} at The option path, which prefixes the failure.
+ * @returns {T} `value`, unchanged.
+ */
+export let hostOptions = (value, keys, at) => {
+  if (value == null) return value;
+  if (!plain(value)) fail(at + ": expected an object");
+  closed(value, keys, at);
+  return value;
+};
+
+/** The three document properties a host may write. */
+let PROPERTIES = ["title", "author", "subject"];
+
+// Nullish is absence here too, one level down: a host writing
+// `{ title: config.title }` over a config that carries no title has made no
+// mistake, and a target skips the property the same way it skips a key that
+// was never written.
+/** @type {(value: any, at: string) => void} */
+let everyString = (value, at) => {
+  for (let key of Object.keys(value))
+    if (value[key] != null && typeof value[key] !== "string")
+      fail(at + "." + key + ": expected a string");
+};
+
+/**
+ * The `meta` option every document target takes, validated whole: those three
+ * properties, each a string, and never a date. What a host cannot write is
+ * what keeps a render reproducible -- each of these formats has one part with
+ * a slot for a clock, and none of them has a way to fill it.
+ *
+ * The contract is one thing, so it is checked in one place. What stays a
+ * target's own is the name each property carries in its format.
+ *
+ * Returns a **copy**, so the properties are read once, here. A host that
+ * mutates its options object between renders cannot make one configured
+ * target write two different documents, and no target has to remember to
+ * copy for itself.
+ *
+ * @param {any} value The `meta` option.
+ * @param {string} at The option path, which prefixes the failure.
+ * @returns {any} A copy of `value`, or undefined when the host wrote none.
+ */
+export let hostMeta = (value, at) => {
+  hostOptions(value, PROPERTIES, at);
+  if (value == null) return undefined;
+  everyString(value, at);
+  return { ...value };
+};

package/lib/index.d.ts

@@ -367,11 +367,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 +668,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 +679,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,7 +696,10 @@ export interface GroupStartEvent {
   depth: number;
   key: unknown;
   aggregates: Record<string, unknown>;
+  /** 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. */
@@ -692,6 +710,8 @@ 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 +786,21 @@ 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>;
+
 /**
  * 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 +810,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.
@@ -920,6 +952,33 @@ export function isDiagnostic(e: unknown): e is QuarioDiagnostic;
  */
 export function imageError(path: string | undefined, said: string, cause?: unknown): Error;
 
+/** Optional document information; never includes dates, so output stays deterministic. */
+export interface QuarioMeta {
+  title?: string;
+  author?: string;
+  subject?: string;
+}
+
+/**
+ * Close a **target factory's** option key set, for the target itself to call.
+ * A target refuses what it does not understand at the factory call, so a
+ * host's typo costs one stack trace where they wrote it rather than an option
+ * silently lost. Throws a `TypeError` prefixed with `at`.
+ *
+ * Nullish is absence. Own enumerable keys only, so an inherited property is
+ * not reported back as an option the host wrote.
+ */
+export function hostOptions<T>(value: T, keys: readonly string[], at: string): T;
+
+/**
+ * Validate a target's `meta` option whole: `title`, `author` and `subject`,
+ * each a string, and nothing else. Every document target takes the same three,
+ * so the contract is checked once; the name each property carries inside a
+ * given format stays that target's own. Throws a `TypeError` prefixed with
+ * `at`.
+ */
+export function hostMeta<T extends QuarioMeta | null | undefined>(value: T, at: string): T;
+
 /**
  * Join a token stream to display text: literals verbatim, values through
  * `display()`. Re-exported from sjabloon.

package/lib/index.js

@@ -24,7 +24,7 @@ import { opt } from "./stream.js";
 // The event stream's public seam, single-sourced in ./stream.js, and the
 // diagnostic predicate in ./locate.js. Re-exported here because a consumer
 // imports them from the package, not from a file inside it.
-export { breathe, display, isReportBand, styledRuns, text, typed, walk } from "./stream.js";
+export { breathe, display, isReportBand, splits, styledRuns, text, typed, walk } from "./stream.js";
 export { format } from "./format.js";
 export {
   currencyOf,
@@ -34,6 +34,7 @@ export {
   STYLE_NAMES,
 } from "./style.js";
 export { imageError, isDiagnostic } from "./locate.js";
+export { hostMeta, hostOptions } from "./host.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */