quario 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # 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

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
@@ -261,7 +281,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,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/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.

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,

package/lib/license.js

@@ -11,7 +11,7 @@
 // though nothing reassigns them. A key is valid for every version released inside its window
 // (LICENSE section 7), so validity compares ISO date strings and never reads
 // a clock — accepted output stays accepted.
-let RELEASE = "2026-09-15"; // release-date
+let RELEASE = "2026-09-19"; // release-date
 // The verifying half of the signing pair: the 65-byte uncompressed P-256
 // point, base64url. The private half never enters the repo;
 // scripts/license/sign.mjs mints keys against it.

package/lib/locate.js

@@ -41,14 +41,12 @@ export let fault = (path, msg) => {
  * An image failure a **target** raises, named on the item that asked for the
  * bytes. The engine vouches for an image's magic numbers and no further
  * (SCHEMA.md, "Image item"), so every failure past that point belongs to
- * whichever target was sizing or embedding the file — and each of them was
- * inventing its own wording, down to a corrupt PNG reaching a host as
- * pdf-lib's bare "Invalid typed array length: 0" (quario-e0bz).
+ * whichever target was sizing or embedding the file, and one wording serves
+ * all of them.
  *
- * Here rather than in a target because three of them raise it and no two of
- * them may depend on each other; the engine is what they all already have.
- * Minted rather than thrown, unlike `fault` beside it, so a caller can raise
- * it from a `catch` or a rejection in whichever style its own code is.
+ * Here rather than in a target because three of them raise it and no two may
+ * depend on each other. Minted rather than thrown, unlike `fault` beside it,
+ * so a caller can raise it from a `catch` or a rejection.
  *
  * The shape is the one every render error has: the path prefixes the message
  * and the failing class survives behind it. It carries no `LOCATION` and is no

package/lib/math.js

@@ -7,37 +7,28 @@
  * error.
  *
  * `round`, `floor` and `ceil` round the DECIMAL the author wrote, not the
- * binary double it is stored as, and `Intl.NumberFormat` is how they reach it:
- * its rounding starts from the shortest decimal that round-trips, so
- * `round(2.675, 2)` is 2.68 where `Math.round(2.675 * 100) / 100` is 2.67 and
- * `Number((2.675).toFixed(2))` is also 2.67. Those two disagree with each other
- * as well as with us, on different inputs -- the whole argument, with the
- * table, is in docs/adr/0050. The locale is hardcoded `en-US` rather than the
- * instance's: this is arithmetic, not presentation, and a locale with
+ * binary double it is stored as, and `Intl.NumberFormat` is how they reach
+ * it: its rounding starts from the shortest decimal that round-trips, so
+ * `round(2.675, 2)` is 2.68 where both `Math.round(2.675 * 100) / 100` and
+ * `Number((2.675).toFixed(2))` are 2.67 (docs/adr/0050). The locale is
+ * hardcoded `en-US`: this is arithmetic, not presentation, and a locale with
  * non-ASCII digits or its own grouping would not parse back through `Number`.
  */
 import { boundedMemo } from "./memo.js";
 
 // The formatters are memoised behind `./memo.js`, the same seam `format()`
-// uses -- one bounded store each, not one between them. ADR 0050 declined this
-// cache and records why the decline expired; what is here is what only this
-// call site knows, its key and its cap.
+// uses — one bounded store each, not one between them (docs/adr/0050).
 //
 // **The key is the mode and the count**, which is all that varies: the locale
-// and `useGrouping` are constants here rather than configuration, precisely so
-// the answer parses back through `Number`, so they are not in it. The mode
-// leads, as the kind does in `format()`'s key, and the two shapes read the
-// same way. Drop either piece and a `floor` presents a `round`'s answer, or a
-// three-digit call presents two -- pinned a piece at a time in
+// and `useGrouping` are constants here, precisely so the answer parses back
+// through `Number`. Drop either piece and a `floor` presents a `round`'s
+// answer, or a three-digit call presents two — pinned a piece at a time in
 // `test/frozen.test.js`.
 //
 // **The cap is unreachable, and that is the point of stating it.** `places`
 // admits 0 to 100 and there are three modes, so this store holds at most 303
-// entries however hostile the data is -- `n` may be an `=` result, but it
-// cannot be an unbounded one. 512 is headroom over that rather than a
-// threshold: if the admitted range ever widened, the store would empty and
-// rebuild rather than grow without limit, which is the same degradation
-// `format()`'s cap buys and no correctness knob either way.
+// entries however hostile the data is. 512 is headroom, so a widened range
+// would empty and rebuild the store rather than grow it without limit.
 let memo = boundedMemo(512);
 
 /** @type {(x: number, n: number, mode: string) => number} */

package/lib/plan.js

@@ -154,6 +154,23 @@ let TEXT_SLOT_KEYS = [...TEXT_KEYS, "width"];
 let IMAGE_KEYS = ["type", "source", "fit", "alt", "visible", "style"];
 let IMAGE_SLOT_KEYS = [...IMAGE_KEYS, "width"];
 
+// A group's two structural literals. `break` names a position rather than a
+// unit (ADR 0077), and this table is the whole of what its four values mean:
+// every boundary `between` consecutive instances turns a page, `lead` adds the
+// run's own leading edge, and `trail` its trailing one. One row says everything
+// about one value, so a reader checks a value by reading it rather than by
+// intersecting sets. `reset` names a page-number sequence and turns nothing.
+let EDGES = new Map([
+  ["before", { between: "page", lead: "page", trail: null }],
+  ["between", { between: "page", lead: null, trail: null }],
+  ["after", { between: "page", lead: null, trail: "page" }],
+  ["around", { between: "page", lead: "page", trail: "page" }],
+]);
+// The `break` values that leave the run's leading edge alone, and so cannot
+// carry a `reset`. Read off the table, so it cannot drift from it.
+let UNLED = new Set([...EDGES].filter(([, edges]) => !edges.lead).map(([value]) => value));
+let RESETS = new Set(["page"]);
+
 // Which detail events carry the row's running values: the ones holding a cell.
 // A split's bracket holds none, so run rides the item and image events inside
 // it rather than the bracket around them.
@@ -236,21 +253,15 @@ let formatsMoney = (block) => {
 };
 
 // One pass over a report's constants: it checks each value, copies it, and
-// freezes the copy. Copying is what keeps a consumer from reaching back into
-// the compiled schema through a nested object; freezing is what stops them
-// mutating what they were handed.
+// freezes the copy. Copying keeps a consumer from reaching back into the
+// compiled schema through a nested object; freezing stops them mutating what
+// they were handed.
 //
-// The vocabulary is JSON's, not structured clone's, because the document a
-// report is written in is JSON (SCHEMA.md, "Deliberate asymmetries"): a Date,
-// a Map or a typed array cannot appear in one, so accepting them here would
-// only ever serve a schema built in JS -- and it is what forced the caveat
-// about the values freezing cannot lock. Rejecting them makes the freeze
-// total. NaN and Infinity go with them: JSON cannot hold either, and
+// The vocabulary is JSON's, not structured clone's, because a report document
+// is JSON (SCHEMA.md, "Deliberate asymmetries"): rejecting a Date, a Map or a
+// typed array makes the freeze total. NaN and Infinity go with them —
 // coercing them to null would turn a definition error into a wrong value
-// three bands away.
-//
-// `seen` rejects cycles rather than surviving them, for the same reason: a
-// JSON document has no way to write one.
+// three bands away — and `seen` rejects cycles, which JSON cannot write.
 /** @type {(value: any) => boolean} */
 let isJsonAtom = (value) =>
   value === null || typeof value === "boolean" || typeof value === "string";
@@ -485,17 +496,15 @@ let runProp = (expression, path, source) => (scope) => {
 };
 // The [live field](../../../CONTEXT.md#live-field): which page value a token
 // *is*, for a target whose own format numbers pages. sjabloon offers each
-// interpolation's expression source once, while compiling, which is the only
-// place the words the author wrote still exist -- a rendered token carries the
-// number and nothing about where it came from. Reading the source here instead
-// is what hard constraint 2 forbids, and a sentinel bound to `page.number` was
-// ruled out because xprsn's `==` is strict: it would break `=page.number == 1`.
+// interpolation's expression source once while compiling, the only place the
+// author's words still exist. Reading the source here instead is what hard
+// constraint 2 forbids, and a sentinel bound to `page.number` was ruled out
+// because xprsn's `==` is strict: it would break `=page.number == 1`.
 //
-// One table for the whole compile: the answer depends on the expression alone,
-// never on where the cell sits. A Map rather than a lookup object, because the
-// key is author source and nothing reached through `Object.prototype` is an
-// answer to this question; each name is written once and is its own answer,
-// frozen because every cell that says it shares the one object.
+// One table for the whole compile: the answer depends on the expression
+// alone. A Map rather than a lookup object, because the key is author source
+// and nothing reached through `Object.prototype` answers this. Frozen,
+// because every cell that says a name shares the one object.
 const PAGE_FIELDS = /** @type {Map<string, { field: import("./index.js").PageField }>} */ (
   new Map(["page.number", "page.total"].map((field) => [field, Object.freeze({ field })]))
 );
@@ -558,13 +567,10 @@ let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
   // rendered over quario's own scope chain, which already binds the anchors:
   // `$` at the render base, `@` on the detail row, neither anywhere else — so
   // a group or report band leaves `@` unbound and a stray `@.field` throws.
-  // sjabloon's `bound` excludes its loop vars / `$` / `@` and quario's engine
-  // names alike from the reported `names`. A render yields the cell's public
-  // token stream: literal runs verbatim plus each interpolation's
-  // pre-stringify value. Templates have no raw form — a `{{{ }}}` tag is a
-  // located SJABLOON_RAW_TAG definition error — so escaping is entirely a
-  // render-target concern at the markup edge, with no exceptions to carry
-  // through the stream.
+  // sjabloon's `bound` excludes its loop vars, `$`, `@` and quario's engine
+  // names from the reported `names`. Templates have no raw form — a
+  // `{{{ }}}` tag is a located SJABLOON_RAW_TAG definition error — so
+  // escaping is entirely a render target's concern at the markup edge.
   /** @type {(str: any, path: string) => (scope: Scope) => any} */
   let cell = (source, path) => {
     let tokens = compileCell(asText(source), path, source, FNS, BND);
@@ -692,12 +698,10 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
   // warning rather than a definition error because the kind is a *later* edit
   // away and an editor session must never refuse a document mid-edit.
   //
-  // The `currency` is read off `entries` rather than off the block, so one the
-  // vocabulary already refused earns no second entry about that declaration:
-  // `entries` is exactly what survived `check`. The `format` beside it is read
-  // as written, because a `format` that was refused is a kind the engine will
-  // not have either -- the code is unread all the same, and saying so is not a
-  // second entry about the same key.
+  // The `currency` is read off `entries`, exactly what survived `check`, so
+  // one the vocabulary already refused earns no second entry. The `format`
+  // beside it is read as written: a refused `format` is a kind the engine
+  // will not have either, so the code is unread all the same.
   /** @type {(block: any, path: string, entries: StyleEntry[]) => void} */
   let unreadCurrency = (block, path, entries) => {
     if (!entries.some(([name]) => name === "currency")) return;
@@ -739,13 +743,11 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
   // a guarded name that answers is written where it was declared rather than
   // after the ones that never needed guarding.
   //
-  // `format` resolves after the loop rather than inside it, and the order is
-  // what makes that necessary: a `currency` kind takes its digit count from
-  // the code the cell wears, so the code has to have been written -- or
-  // voided by `guarded` -- before the kind can be resolved over it. Doing it
-  // per entry would make one declaration depend on where another sits in the
-  // block. The instance's options come with it, for the cell that declares no
-  // code of its own and takes the instance's (docs/adr/0056).
+  // `format` resolves after the loop, not inside it: a `currency` kind takes
+  // its digit count from the code the cell wears, so the code must have been
+  // written — or voided by `guarded` — first. Per entry would make one
+  // declaration depend on where another sits in the block. The instance's
+  // options come with it, for a cell declaring no code (docs/adr/0056).
   /** @type {(entries: StyleEntry[]) => (scope: Scope) => Scope} */
   let blockFn = (entries) => (scope) => {
     /** @type {Scope} */
@@ -912,16 +914,13 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
   // settle it. That is the whole of why the warning below is incomplete by
   // construction (SCHEMA.md, "Validation").
   //
-  // The two delimiters are the one place quario names sjabloon's syntax rather
-  // than asking for it, and hard constraint 2 is why that is written down here
-  // instead of passing unremarked. It is a *shape* test and not a parse:
-  // nothing is tokenised, extracted or evaluated, the compile above stays the
-  // only thing that reads the source, and the answer decides an advisory alone.
-  // It has no false positives -- text outside every tag cannot be conditional,
-  // since a block opens with `{{#`, and sjabloon strips no whitespace around a
-  // standalone tag -- so a wrong answer costs a missing warning, never a
-  // warning on a correct document. A value that is not one template is not this
-  // question at all: a run array's runs each answer it for themselves.
+  // The two delimiters are the one place quario names sjabloon's syntax
+  // rather than asking for it (hard constraint 2). It is a *shape* test, not
+  // a parse: nothing is tokenised or evaluated, and the answer decides an
+  // advisory alone. It has no false positives — text outside every tag cannot
+  // be conditional, a block opening with `{{#`, and sjabloon strips no
+  // whitespace around a standalone tag — so a wrong answer costs a missing
+  // warning, never a warning on a correct document.
   /** @type {(src: any) => boolean} */
   let neverPresents = (src) =>
     typeof src === "string" && !(src.startsWith("{{") && src.endsWith("}}"));
@@ -1582,17 +1581,16 @@ let bands = (
     keys(value.header, ["style"], "detail.header");
     return rowStylesOf(value.header, "detail.header");
   };
-  // Which slot each column's header sits in -- the same invariant a total row's
-  // cells carry, walked positionally rather than summed because the diagnostic
-  // has to name the column it broke at. Read off the raw definitions, before
-  // any column is parsed, so `columnOf` can report its verdict in the column's
-  // own turn. Spans are read leniently: an unreadable one covers a single
-  // column and gets its own diagnostic when the column is parsed.
+  // Which slot each column's header sits in, walked positionally rather than
+  // summed because the diagnostic has to name the column it broke at. Read
+  // off the raw definitions, before any column is parsed, so `columnOf` can
+  // report its verdict in the column's own turn. An unreadable span covers a
+  // single column and gets its own diagnostic there.
   //
-  // `own` fills its own slot, `covered` is filled by a neighbour's span, `over`
-  // reaches past the last column, and everything after an `over` is
-  // `unreached` -- one broken span should not also report every column behind
-  // it as headerless.
+  // `own` fills its own slot, `covered` is filled by a neighbour's span,
+  // `over` reaches past the last column, and everything after an `over` is
+  // `unreached` — one broken span should not report every column behind it as
+  // headerless.
   // How many columns a definition's header claims, read leniently: a malformed
   // column, a missing header and an unreadable span all claim one here, and
   // each gets its own diagnostic when the column is parsed.
@@ -1799,11 +1797,25 @@ let bands = (
     if (groupNames.has(name)) bad(path, 'duplicate group name "' + name + '"');
     else groupNames.add(name);
   };
-  /** @type {(value: any, path: string, kind: string) => void} */
-  let checkHint = (value, path, kind) => {
-    if (value == null || value === "page") return;
+  /** @type {(value: any, path: string, kind: string,
+   *    known: { has: (value: string) => boolean }) => void} */
+  let checkHint = (value, path, kind, known) => {
+    if (value == null || known.has(value)) return;
     bad(path, "unknown " + kind + ' "' + value + '"');
   };
+  // A group's two structural literals, and the one rule tying them together.
+  // A page-number sequence owns whole pages, so it needs a leading boundary
+  // `break` may not supply (ADR 0077). That is read off the pair, and only for
+  // the values this compile understood: an unknown `break` already has its own
+  // problem, and a second about what it fails to supply would be that one
+  // twice over.
+  /** @type {(def: any, path: string) => void} */
+  let checkHints = (def, path) => {
+    checkHint(def.break, path + ".break", "break", EDGES);
+    checkHint(def.reset, path + ".reset", "reset", RESETS);
+    if (def.reset === "page" && (def.break == null || UNLED.has(def.break)))
+      bad(path + ".reset", 'reset needs break "before" or "around"');
+  };
   /** @type {(aggs: [string, Fold][], rows: any[], scope: Scope, handle: Scope) => Scope} */
   let applyAggs = (aggs, rows, scope, handle) => {
     /** @type {Scope} */
@@ -1840,10 +1852,38 @@ let bands = (
       rows,
     };
   };
+  // One instance's bands, in order, as the events they yield.
+  /** @type {(ctx: any, groupScope: any, ordered: any[], runners: any) => Generator<any>} */
+  let instanceBands = function* (ctx, groupScope, ordered, runners) {
+    yield* ctx.header(groupScope);
+    yield* ctx.inner(ordered, groupScope, runners.extend(ctx.running));
+    yield* ctx.footer(groupScope);
+  };
+  // Pass an instance's events through, and answer whether any of them
+  // occupied the document. Only a group bracket can arrive without something
+  // being there, so an instance holding nothing but hollow instances is hollow
+  // itself, and one holding a child that drew is not.
+  /** @type {(events: Iterable<any>) => Generator<any, boolean>} */
+  let occupied = function* (events) {
+    let drew = false;
+    for (let event of events) {
+      drew ||= event.type !== "group-start" && event.type !== "group-end";
+      yield event;
+    }
+    return drew;
+  };
   /** @type {(ctx: any) => Band} */
   let groupWalk = (ctx) =>
     function* (rows, scope, runners) {
       let parts = Map.groupBy(rows, (row) => ctx.by(withRow(scope, row)));
+      // The four `break` values resolved to `ctx.edges` at compile, so a
+      // target reads boundaries rather than positions: every boundary between
+      // consecutive instances is the later instance's leading edge, and the
+      // run's own two edges fall on its first and its last. The run is this
+      // call's partition, so a nested group's edges belong to the parent
+      // instance holding it rather than to the document.
+      let last = parts.size - 1;
+      let index = 0;
       for (let [key, groupRows] of parts) {
         // A group band has no current row, so `@` stays unbound here.
         let { groupScope, aggregates, rows: ordered } = openInstance(ctx, key, groupRows, scope);
@@ -1856,12 +1896,18 @@ let bands = (
             aggregates,
             path: ctx.path,
           },
-          { break: ctx.pageBreak, reset: ctx.reset, columns: ctx.columns },
+          {
+            break: index > 0 ? ctx.edges.between : ctx.edges.lead,
+            breakAfter: index === last ? ctx.edges.trail : null,
+            reset: ctx.reset,
+            columns: ctx.columns,
+          },
         );
-        yield* ctx.header(groupScope);
-        yield* ctx.inner(ordered, groupScope, runners.extend(ctx.running));
-        yield* ctx.footer(groupScope);
-        yield { type: "group-end", name: ctx.name, depth: ctx.index };
+        let drew = yield* occupied(instanceBands(ctx, groupScope, ordered, runners));
+        // The closing bracket says whether the instance is hollow, so no
+        // target rediscovers it from the stream (docs/adr/0060, as amended).
+        yield opt({ type: "group-end", name: ctx.name, depth: ctx.index }, { hollow: !drew });
+        index++;
       }
     };
   /** @type {(def: any, path: string, defs: any[], index: number, detail: any, columned?: boolean) => Band} */
@@ -1886,8 +1932,7 @@ let bands = (
     named(def.name, path + ".name", RESERVED);
     noteGroup(def.name, path + ".name");
     let by = expression(def.by, path + ".by");
-    checkHint(def.break, path + ".break", "break");
-    checkHint(def.reset, path + ".reset", "reset");
+    checkHints(def, path);
     let columns = columnsOf(def.columns, path + ".columns", columned);
     return groupWalk({
       by,
@@ -1900,7 +1945,7 @@ let bands = (
       inner: bandOf(defs, index + 1, detail, columned || columns != null),
       name: def.name,
       path,
-      pageBreak: def.break,
+      edges: EDGES.get(def.break) ?? NONE,
       reset: def.reset,
       columns,
       index,

package/lib/reducers.js

@@ -5,14 +5,11 @@
  * form `sum(@.lines, l => l.total)` and a declared aggregate alike — a step
  * folded across rows in render order for a declared running value, and a
  * spelling rule, since `count` is the one declared form that takes no
- * expression. Those three used to live in two hand-enumerated tables, a
- * derived name set, and a reducer named in the validator, so adding a reducer
- * was three edits and forgetting the runner passed validation and threw a raw
- * TypeError at render. One entry per reducer; every role derives from it.
+ * expression. One entry per reducer; every role derives from it.
  *
  * `prev` is the entry with no fold. There is no whole-array "previous", so it
- * is a running value only — and that missing half is exactly what keeps it out
- * of an `aggregates` block, where `RUN = AGG ∪ {prev}` used to say so by hand.
+ * is a running value only, and that missing half is what keeps it out of an
+ * `aggregates` block.
  *
  * Coercion is quiet: only a finite number contributes, everything else folds
  * to 0, as the spec promises.
@@ -32,12 +29,22 @@ let num = (value) => {
 // why `countDistinct` reads its lambda this way despite the shared prefix.
 /** @type {(rows: any[] | null | undefined, of?: ((row: any) => any) | null) => any[]} */
 let project = (rows, of) => (rows || []).map((row) => (of ? of(row) : row));
-// `min`/`max` share one shape: project through the lambda, then pick a winner.
-/** @type {(pick: (a: any, b: any) => any) => Reducer} */
-let extreme = (pick) => (rows, of) => {
+// The shape every reducer with no zero shares: project through the lambda,
+// then answer from a nonempty array. An empty one has no answer, so it is
+// `null` -- and an inline caller can tell, because a call is not the member
+// read that normalizes an absent value.
+/** @type {(from: (values: any[]) => any) => Reducer} */
+let folded = (from) => (rows, of) => {
   let values = project(rows, of);
-  return values.length ? values.reduce(pick) : null;
+  return values.length ? from(values) : null;
 };
+// `min`/`max` pick a winner out of the projection. `first`/`last` take an end
+// of it instead, which makes them the only folds that read the array's order
+// rather than only its contents -- so the order a scope hands them is
+// author-visible where no other reducer's is. SCHEMA.md, "Aggregates", says
+// which order each scope hands.
+/** @type {(pick: (a: any, b: any) => any) => Reducer} */
+let extreme = (pick) => folded((values) => values.reduce(pick));
 /** @type {Reducer} */
 let sum = (rows, of) => (rows || []).reduce((total, row) => total + num(of ? of(row) : row), 0);
 
@@ -45,9 +52,10 @@ let sum = (rows, of) => (rows || []).reduce((total, row) => total + num(of ? of(
  * The table. Each entry is one reducer entire: how it folds an array, how it
  * steps a row, and whether its declared form carries `:=<expression>`.
  *
- * The running halves fold in render order. `min`/`max` have no zero, so they
- * seed to the first row's value — the one deliberate `undefined` here, since
- * xprsn reads absent values as null.
+ * The running halves fold in render order. `min`, `max` and `first` have no
+ * zero, so they seed to the first row's value — the deliberate `undefined`s
+ * here, since xprsn reads absent values as null and a runner's step only ever
+ * sees what an xprsn expression returned.
  * @type {Record<string, Entry>}
  */
 let REGISTRY = {
@@ -104,6 +112,23 @@ let REGISTRY = {
     },
     expr: true,
   },
+  first: {
+    fold: folded((values) => values[0]),
+    run: () => {
+      let opened = /** @type {any} */ (undefined);
+      return (value) => (opened = opened === undefined ? value : opened);
+    },
+    expr: true,
+  },
+  last: {
+    // The runner is the identity on purpose: the last row seen *is* this row,
+    // so `run.last` says what `@` already says. It exists because the run
+    // vocabulary is the reducer vocabulary, and SCHEMA.md states it rather
+    // than leaving the derivation to surprise an author (ADR 0006).
+    fold: folded((values) => values.at(-1)),
+    run: () => (value) => value,
+    expr: true,
+  },
   prev: {
     fold: null,
     run: () => {
@@ -177,19 +202,16 @@ let aLambda = demands(
 // nothing at all.
 //
 // The guard wraps the table's own entries because this is the one place the
-// reducer's name is in hand to say. Only one of the two consumers can carry an
-// authored mistake -- `plan.js` spreads this record into an expression's
-// function scope, where the arguments are whatever the author wrote -- while
-// `scope.js` folds rows the engine grouped through a compiled lambda, so
-// neither demand can fire there. That dead check is the price of one door
-// instead of two, and it is a comparison per fold, not per row. Nullish passes
-// both: an absent read is null, so `sum(@.lines)` on a row with no lines folds
-// the empty array, which is the answer the spec's six give.
+// reducer's name is in hand to say. Only `plan.js` can carry an authored
+// mistake here, since `scope.js` folds rows the engine grouped through a
+// compiled lambda; that dead check is the price of one door instead of two,
+// and it costs a comparison per fold, not per row. Nullish passes both: an
+// absent read is null, so `sum(@.lines)` on a row with no lines folds the
+// empty array.
 //
 // It carries no engine code: the mistake is quario's own verdict on an
-// authored call, like `round`'s bad `n`, and SCHEMA.md's "Validation" tells a
-// host to recognise a located error with `isDiagnostic` rather than by probing
-// a `code` anything could fake.
+// authored call, and SCHEMA.md's "Validation" tells a host to recognise a
+// located error with `isDiagnostic` rather than by probing a `code`.
 /** @type {(fn: string, fold: Reducer) => Reducer} */
 let guarded = (fn, fold) => (rows, of) => {
   anArray(fn, rows);

package/lib/stream.js

@@ -93,11 +93,9 @@ export let reviveDate = (value) => {
  *
  * Passing the cell's resolved `format` declaration opts into the one coercion
  * the seam performs: under the `date` kind, a string in either accepted RFC
- * 3339 form revives to the `Date` it names. The gate is the declaration, and
- * the kind is `date` alone, because a date is the one type a JSON document
- * cannot carry — a number arrives as a number, so no other kind has anything
- * to revive (ADR 0041). Callers that read no style omit the argument and see
- * the seam exactly as it was.
+ * 3339 form revives to the `Date` it names. `date` alone, because a date is
+ * the one type a JSON document cannot carry (ADR 0041). Callers that read no
+ * style omit the argument.
  *
  * @param {any[]} tokens A cell's tokens.
  * @param {unknown} [decl] The cell's resolved `format` declaration — the
@@ -112,13 +110,11 @@ export function typed(tokens, decl) {
 }
 
 /**
- * Whether a token list renders exactly one value token -- the seam `typed()`
- * gates on, and the same one `format` is read under. A run holding a literal
- * and an interpolation, or two interpolations, presents no single value, so a
- * declaration that presents a value has nothing to speak about (ADR 0061).
- *
- * Internal to the package: `typed()` is the public reading of it, and the
- * traversal asks it of the tokens each style block governs.
+ * Whether a token list renders exactly one value token — the seam `typed()`
+ * gates on, and the same one `format` is read under. A run holding two
+ * interpolations presents no single value, so a declaration that presents a
+ * value has nothing to speak about (ADR 0061). Internal: `typed()` is the
+ * public reading of it.
  *
  * @type {(tokens: any[]) => boolean}
  */
@@ -156,13 +152,9 @@ let joins = (last, style) => !!last && sameStyle(last.style, style);
 
 /**
  * Group a cell's tokens into its styled runs, in order. Consecutive tokens
- * with equal styles are one run — a lossless rule, because equal styles render
- * identically, so grouping survives a JSON round trip and a target that
- * reserialized the stream reads the same runs back.
- *
- * Shipped so the built-in targets and a custom one cannot drift: the stream
- * carries a cell's runs flattened into one `tokens` array with an optional
- * per-token `style`, and this is the whole rule for reading them back
+ * with equal styles are one run — lossless, so grouping survives a JSON round
+ * trip. Shipped so the built-in targets and a custom one cannot drift: this
+ * is the whole rule for reading a cell's flattened `tokens` back
  * (SCHEMA.md, "Event stream"; ADR 0061).
  *
  * @param {any[]} tokens A cell's tokens.
@@ -194,11 +186,10 @@ let REPORT_BANDS = new Set([
 ]);
 
 /**
- * Whether a band item's `role` names one of the report's own bands rather than
- * a group instance's. This says whose band it is, never how to lay one out —
- * what a consumer does with the answer is its own. See SCHEMA.md ("Event
- * stream") for the contract and ADR 0028 for why the engine classifies rather
- * than carrying a verdict on the events themselves.
+ * Whether a band item's `role` names one of the report's own bands rather
+ * than a group instance's. This says whose band it is, never how to lay one
+ * out. ADR 0028 says why the engine classifies rather than carrying a verdict
+ * on the events themselves.
  *
  * @param {string} role An item or image event's `role`.
  * @returns {boolean} True for the report's own bands.
@@ -207,22 +198,18 @@ export function isReportBand(role) {
   return REPORT_BANDS.has(role);
 }
 
-// The cooperative hand-back's plumbing. A timer is the slowest way a runtime will
-// hand the loop back and, until this landed, the only one quario used: measured
-// on an M-series Mac it costs ~1.20ms per hand-back against ~0.015ms for
-// setImmediate, so a 10k-row render spent about 30% of its wall-clock waiting
-// on timers. Browsers are worse — once nested-timer depth passes five, the
-// HTML spec clamps a zero timer to 4ms, i.e. ~4ms per batch on a long report.
-// Deliberately not scheduler.yield(): it is Chrome-only, and its continuation
-// is scheduled ahead of other host tasks, which is the opposite of what handing
-// the loop back is for. The timer stays as the last rung for a runtime that
-// offers neither of the others; no runtime quario supports reaches it.
+// The cooperative hand-back's plumbing. A timer is the slowest rung: ~1.20ms
+// per hand-back against ~0.015ms for setImmediate, so a 10k-row render spent
+// about 30% of its wall-clock on timers. Browsers are worse — past a
+// nested-timer depth of five the HTML spec clamps a zero timer to 4ms.
+// Deliberately not scheduler.yield(): Chrome-only, and its continuation is
+// scheduled ahead of other host tasks, the opposite of what handing the loop
+// back is for. The timer stays as the last rung, which no runtime quario
+// supports reaches.
 //
-// setImmediate is Node's alone, so reaching it is a feature detection and not
-// an import: this module runs in browsers too, where importing node:timers
-// would not resolve. The lookup goes through globalThis because the package's
-// types are deliberately DOM-only (only @quario/xlsx pulls Node's in) — a
-// typed global would mean a dependency for one name.
+// setImmediate is Node's alone, so reaching it is a feature detection rather
+// than an import: this module runs in browsers, where node:timers would not
+// resolve. Through globalThis because the package's types are DOM-only.
 let immediate = /** @type {any} */ (globalThis).setImmediate;
 /** @type {MessageChannel | undefined} */
 let channel;
@@ -265,13 +252,10 @@ export async function breathe() {
  * so a target writes no event loop of its own — in stream order, exactly once
  * each, pulled lazily, handing the loop back every 1000 events. A missing
  * handler ignores that event, a handler that throws rejects without draining
- * the rest, and handlers are synchronous: a promise one returns is not
- * awaited. The stream's first event reaches its handler before a second one is
- * pulled, so a target settles what it needs from `report-start` — page band
- * closures, the marking — in that handler rather than pulling the stream
- * itself. No opening event is required: the driver reads `event.type` and
- * nothing else, so a stream that starts part-way through walks like any other.
- * See SCHEMA.md ("The walk driver"), which is normative.
+ * the rest, and handlers are synchronous. The first event reaches its handler
+ * before a second is pulled, so a target settles what it needs from
+ * `report-start` there. No opening event is required: the driver reads
+ * `event.type` and nothing else. SCHEMA.md ("The walk driver") is normative.
  *
  * @param {Iterable<any>} events One render's event stream.
  * @param {Record<string, (event: any) => void>} handlers Per-event handlers.
@@ -285,6 +269,48 @@ export async function walk(events, handlers) {
   }
 }
 
+// What each event does to the bracket being folded, and what it yields, if
+// anything. Outside a bracket an event passes straight through; inside, it is
+// a slot. A stray `split-end` with no opening -- a stream taken up part-way --
+// yields nothing.
+/** @type {Record<string, (fold: { bracket: any }, event: any) => any>} */
+let FOLD = {
+  "split-start": (fold, event) => {
+    fold.bracket = { ...event, type: "split", items: [] };
+    return null;
+  },
+  "split-end": (fold) => {
+    let out = fold.bracket;
+    fold.bracket = null;
+    return out;
+  },
+};
+/** @type {(fold: { bracket: any }, event: any) => any} */
+let plain = (fold, event) => {
+  if (!fold.bracket) return event;
+  fold.bracket.items.push(event);
+  return null;
+};
+
+/**
+ * The split bracket, folded: `split-start`, the slot events between, and
+ * `split-end` become one `split` event wearing the opening's `role`, `path`,
+ * `slots` and `style`, with the slot events in order under `items`. Every
+ * other event passes through untouched, lazily, so a consumer that wants a
+ * split whole reads `splits(stream)` instead of keeping a bracket of its own.
+ * SCHEMA.md ("The walk driver") is normative.
+ *
+ * @param {Iterable<any>} events One render's event stream.
+ * @returns {Generator<any, void>} The same stream, each bracket one event.
+ */
+export function* splits(events) {
+  let fold = { bracket: null };
+  for (let event of events) {
+    let out = (FOLD[event.type] ?? plain)(fold, event);
+    if (out) yield out;
+  }
+}
+
 // Optional public event fields are present only when truthy — the one rule
 // for optional event data, owned here. What rides it is therefore any value
 // whose falsy form means "undeclared"; a field whose zero or empty string is

package/lib/style.js

@@ -9,13 +9,8 @@
  * The **resolutions** are what a declaration means before any target sees it.
  * A row's box is the one there is (SCHEMA.md, "Style declarations"): it says
  * what the document means rather than what a surface paints, so every target
- * is handed the answer instead of reaching its own. That is the same line
- * `./stream.js` sits on, and the opposite side of it from `finite`/`HEX`,
- * which are restated per target on purpose because a coercion is each target's
- * own edge.
- *
- * Past those, each target maps these names to its own formatting model, and
- * nothing here knows about any of them.
+ * is handed the answer. `finite`/`HEX` sit on the other side of that line and
+ * are restated per target, a coercion being each target's own edge.
  */
 import { record } from "./names.js";
 import { defaultDigits } from "./precision.js";
@@ -147,10 +142,9 @@ export let FORMAT_VOCABULARY = Object.freeze({
  * the guard every name from a document gets: a `kind` resolved off
  * `Object.prototype` is not a kind.
  *
- * Exported because the typed-cell seam asks the same question and only that
- * question: `typed()` gates its one coercion on the kind being `date`, and
- * resolving a whole declaration to read one field off it would allocate per
- * cell for nothing (`./stream.js`).
+ * Exported because `typed()` asks the same question and only that question:
+ * resolving a whole declaration to read one field would allocate per cell
+ * for nothing (`./stream.js`).
  *
  * @type {(value: any) => string | undefined}
  */
@@ -398,19 +392,15 @@ export let checkRowStyle = withoutNames(ROW_NAMES, checkStyle, "a table row");
 // --- resolution --------------------------------------------------------------
 
 // A resolved `=` result the vocabulary rejects, judged once where every style
-// block resolves rather than at each surface that would read it. What the
-// declaration falls back *to* decides what becomes of it, and that question
-// partitions the vocabulary three ways -- omitted, kept, voided. The argument
-// for each is docs/adr/0055; what is restated here is only which is which, and
-// why the two exceptions cannot be folded into the general rule.
+// block resolves. What the declaration falls back *to* partitions the
+// vocabulary three ways — omitted, kept, voided (docs/adr/0055).
 //
-// A literal never reaches here: `checkStyle` already refused it at compile, so
-// only an `=` entry is ever guarded.
+// A literal never reaches here: `checkStyle` refused it at compile, so only
+// an `=` entry is ever guarded.
 //
-// `format` then takes one more step that no other name needs, below: whatever
-// survives is **resolved**, the shorthand widened and the kind's own answer
-// filled in, because what crosses the stream is the declaration with its digit
-// count or its form already on it (docs/adr/0056).
+// `format` then takes one more step below: whatever survives is **resolved**,
+// the shorthand widened and the kind's own answer filled in, so what crosses
+// the stream carries its digit count or its form (docs/adr/0056).
 
 // The sentinel a failed result becomes when its name is one the engine omits.
 // A symbol, so nothing an expression can evaluate to is ever equal to it --
@@ -424,20 +414,16 @@ export let SKIP = Symbol("skip");
  * Wrap a style entry's compiled `=` result in the rule its name answers to.
  *
  * **Omitted** is the general rule and needs no branch: the key is never
- * written, so the layer below stands. That is what the spec means by
- * "contributes nothing, same as omit" (SCHEMA.md, "Style declarations") -- a
- * report-header item whose `bold` returns `1`, or whose `size` returns
- * `"big"`, keeps its band-role bold and its band-role size rather than losing
- * them to a value no target can read. It is the rule for the box too: side
- * ownership is settled over the names a block declares, before any of this
- * resolves, so dropping a rejected `borderTopColor` cannot hand the cell its
- * row's other two (docs/adr/0062).
+ * written, so the layer below stands — "contributes nothing, same as omit"
+ * (SCHEMA.md). It is the rule for the box too: side ownership is settled over
+ * the names a block declares, before any of this resolves, so dropping a
+ * rejected `borderTopColor` cannot hand the cell its row's other two
+ * (docs/adr/0062).
  *
- * **Voided** is `currency` alone. Its fallback is not the layer below but the
- * instance's own code, so omitting would present one denomination's money
- * under another's name -- the one failure louder than no formatting at all.
- * `null` keeps the cell's answer, which nothing can present, so the cell drops
- * to `display()` as a bogus `format` kind does (docs/adr/0041).
+ * **Voided** is `currency` alone. Its fallback is the instance's own code,
+ * not the layer below, so omitting would present one denomination's money
+ * under another's name. `null` keeps an answer nothing can present, so the
+ * cell drops to `display()` (docs/adr/0041).
  *
  * @type {(name: string, resolve: (scope: any) => any) => (scope: any) => any}
  */
@@ -506,10 +492,8 @@ let presentedNumber = (kind, own, style, options) => {
  * own answer and no consumer computes one (docs/adr/0053, docs/adr/0056).
  *
  * A `currency` whose code Intl will not read resolves to a kind with **no**
- * `digits` — the withdrawal that leaves the worksheet writing no number
- * format. A declared `digits` still crosses there: it resolved on its own
- * terms, and making it depend on a sibling declaration would be a special
- * case bought for nothing.
+ * `digits`, the withdrawal that leaves the worksheet writing no number
+ * format. A declared `digits` still crosses: it resolved on its own terms.
  *
  * @param {{ format?: unknown, currency?: unknown } | null} [style] A cell's style.
  * @param {{ currency?: string } | null} [options] The instance's options.
@@ -529,15 +513,10 @@ export let formatOf = (style, options) => {
  * past `guarded` that a name needs here, and the last thing a style block has
  * done to it before a target sees it (docs/adr/0056).
  *
- * By the time this runs the declaration is already sound: a literal passed
- * `checkStyle` at compile, and an `=` result passed `guarded`, which omits a
- * kind it cannot read the way it omits any other rejected value. So the
- * `delete` below is not the omit rule -- that is `guarded`'s -- but the answer
- * to a kind that reads and still presents nothing, which today is only a
- * `currency` whose code Intl will not take.
- *
- * The block is returned rather than mutated silently, because it is the value
- * `styleFn` hands on.
+ * By the time this runs the declaration is sound: a literal passed
+ * `checkStyle` at compile, an `=` result passed `guarded`. So the `delete`
+ * below is not the omit rule but the answer to a kind that reads and still
+ * presents nothing — today only a `currency` whose code Intl will not take.
  *
  * @type {(style: any, options?: any) => any}
  */
@@ -556,9 +535,8 @@ export let resolveFormat = (style, options) => {
  * rather than once per helper.
  *
  * A resolved style already carries the answer, and a target reads it off the
- * declaration rather than calling this. What this is for is a host holding a
- * style the stream has not resolved: the shorthand is widened here first, so
- * either may be asked.
+ * declaration rather than calling this. This is for a host holding a style
+ * the stream has not resolved: the shorthand is widened here first.
  *
  * @param {{ format?: unknown, currency?: unknown } | null} [style] A cell's style.
  * @param {{ currency?: string } | null} [options] The instance's currency code.
@@ -570,14 +548,12 @@ export let fractionDigits = (style, options) => formatOf(style, options)?.digits
 
 // A row's `style` resolves onto its cells (SCHEMA.md, "Style declarations").
 // The box is the half that cannot arrive any other way: a table row is not a
-// box on any surface -- not a `<tr>`, not a worksheet row, not a band of the
-// PDF's own -- so it is resolved here, once, and no target is left to have an
-// opinion about it. Every other declaration on a row reaches its cells by the
-// layering each target already does, which is why only the box moves.
+// box on any surface, so it is resolved here once and no target is left with
+// an opinion. Every other declaration reaches the cells by the layering each
+// target already does, which is why only the box moves.
 //
-// Which names are the box is decided where the block is compiled, not here: a
-// literal row style is partitioned once per table rather than once per row.
-// So is which of them reaches which cell -- see `boxReaching`. What is left
+// Which names are the box, and which reach which cell, are decided where the
+// block is compiled — once per table rather than once per row. What is left
 // for render is writing the answer.
 
 // The three names of each border side, built once, which is what lets
@@ -591,12 +567,10 @@ let BORDER_NAMES = Object.fromEntries(
  * The names an under-box loses once an over-box has spoken: every name the
  * over-box states, plus the other two of any border side it states one of.
  *
- * This is the whole-side rule, over declaration names rather than resolved
- * objects -- which is all it ever needed, since a compiled block writes every
- * name it declares whatever the values resolve to. Composing the totals block
- * into its rows uses it at compile time, so no third style level survives to
- * render (docs/adr/0049); fanning a row's box onto its cells uses it for the
- * same reason (docs/adr/0062).
+ * The whole-side rule, over declaration names rather than resolved objects: a
+ * compiled block writes every name it declares whatever the values resolve
+ * to. Used composing the totals block into its rows (docs/adr/0049) and
+ * fanning a row's box onto its cells (docs/adr/0062).
  *
  * @type {(names: Iterable<string>) => Set<string>}
  */
@@ -612,12 +586,10 @@ export let coveredNames = (names) => {
  * Which of a row box's names reach one cell: the row's, less everything the
  * cell's own declarations cover. A border side is won whole by the cell that
  * names any of its three parts, so a cell that failed-soft on one name does
- * not pick up the row's other two and become a stroke nobody declared -- the
- * question settled here, once per table, rather than per cell per row.
+ * not pick up the row's other two. Settled once per table.
  *
- * `null` is the answer for a cell that declares no box name at all, which is
- * the common case: the row's box is that cell's box entire, so `fanBox` hands
- * the object over rather than copying it name by name.
+ * `null` is the common case, a cell declaring no box name: the row's box is
+ * that cell's entire, so `fanBox` hands the object over rather than copying.
  *
  * @type {(rowNames: readonly string[], cellNames: readonly string[]) => string[] | null}
  */

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "quario",
-  "version": "0.9.0",
-  "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
+  "version": "0.10.0",
+  "description": "Tiny, CSP-safe report engine for JavaScript. One JSON document renders to HTML, PDF, XLSX, CSV and Word.",
+  "keywords": [
+    "csp",
+    "json",
+    "pdf",
+    "report",
+    "reporting",
+    "xlsx"
+  ],
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -51,7 +59,7 @@
         "sjabloon",
         "padvinder"
       ],
-      "limit": "14 kB"
+      "limit": "14.2 kB"
     }
   ],
   "engines": {