quario 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # quario
 
+## 0.13.0
+
+### Minor Changes
+
+- A band gains a `grid` item: splits that share one column geometry.
+
+  A statement is twenty lines of a label and an amount, on the same two widths. As splits, each line restated its widths:
+
+  ```jsonc
+  { "type": "split", "slots": [
+    { "type": "text", "value": "Opening", "width": 70 },
+    { "type": "text", "value": "{{ @.opening }}", "width": 30, "style": { "align": "right" } }
+  ] }
+  ```
+
+  A grid states the widths, and each column's style, once:
+
+  ```jsonc
+  {
+    "type": "grid",
+    "columns": [{ "width": 70 }, { "width": 30, "style": { "align": "right" } }],
+    "rows": [
+      { "slots": [{ "type": "text", "value": "Opening" }, { "type": "text", "value": "{{ @.opening }}" }] },
+      {},
+      { "slots": [{ "type": "text", "value": "Total" }, { "type": "text", "value": "{{ @.total }}" }], "style": { "bold": true } }
+    ]
+  }
+  ```
+
+  A row is a split without `type`, and it keeps every rule a split has. A column's `style` is the layer under each of its slots, and a slot's own declarations win. A row that names fewer slots than there are columns leaves the rest empty, so `{}` is a spacer line and a one-slot row is a label-only line.
+
+  Each row reaches a target as the split it is, so the event stream does not change and no target needed an update. No existing report changes.
+
+- The package now ships a JSON Schema of the report document.
+
+  The file is `lib/schema.json`, and the package exports it as `quario/schema.json`. Point `$schema` at the installed copy, and an editor checks the document and shows the documentation for each key:
+
+  ```jsonc
+  { "$schema": "./node_modules/quario/lib/schema.json", "data": "$.orders[*]" }
+  ```
+
+  A report document accepts one new top-level key, `$schema`. Its value must be a string. The engine checks the type and reads nothing else, so a document keeps its `$schema` through an upgrade. Anywhere below the top level, `$schema` stays an unknown key.
+
+  The JSON Schema proves the shape of each value, and `validate()` still proves the document. A document can pass the JSON Schema and fail `validate()`: a rule across two values, a reserved name, or an expression that does not compile. The strict structured-output modes of OpenAI and Anthropic do not accept the file, because a report document leaves most of its keys out.
+
+  The TypeScript declarations are stricter in one place. A parameter's value under `params` is now typed as any JSON value except a plain object. The engine always read a plain object there as a declaration, so a document that the new type refuses was never the document it looked like.
+
+- **A license key has an end date and no start date.** A key covers every version released on or before its `to` date. Before, a key also named a `from` date, and a version released before that date stayed marked. The engine now ignores a `from` in a key. When a key ends before the release date of the installed version, the warning names both dates.
+- A value the runtime has no text form for is now a located render error rather than `[object Object]` in the document.
+
+  A cell reaches its reader through `String(value)`. A plain object, a `Map` and a `Set` have no text form of their own, so that falls back to a tag: `[object Object]`, `[object Map]`, `[object Set]`. A tag lays out, paginates and lands in a worksheet cell, and the document is wrong. A few values have no text form at all, and `String()` throws on them — an object with no prototype, a boxed symbol. The engine now refuses both kinds and names the cell:
+
+  ```
+  detail[0].value [{{ @.address }}]: a value with no text form, which would print as [object Object]
+  ```
+
+  The rule reads the value, not its source, so a registered function's result and a data field answer to it alike. A value that says what it is still prints it: a class with its own `toString`, an array (`[1, 2]` prints `1,2`), a `Date`. An absent read still prints nothing. A computed property is outside the rule, because a group's `by` is an identity rather than text — `by: "=@"` makes each row its own instance — and a `where` and a `visible` are read for truth.
+
+  Every entry in the function registry must be a function. `plan` reports one that is not at `functions.<name>`, where before it raised an unhandled `TypeError` out of `plan` itself at a caller who had only asked a question.
+
+  A report that printed `[object Object]` stops rendering. It was printing a value no reader could use.
+
+- A document may now name its paper and turn it, and its margin may name each side.
+
+  ```jsonc
+  {
+    "page": {
+      "size": "letter",
+      "orientation": "landscape",
+      "margin": { "top": 36, "right": 29, "bottom": 36, "left": 29 }
+    }
+  }
+  ```
+
+  `page.size` takes `"A4"` or `"letter"`. A `[width, height]` pair stays a target option. `page.orientation` takes `"portrait"` or `"landscape"`, and it turns whichever paper is in force. `page.margin` still takes one number for all four sides.
+
+  The rule `page.margin` already followed now covers all three keys. The document's key wins where it declares one, a target option applies where it does not, and both declaring the same key is a render error. `orientation` in a document beside a target's `size` is not both.
+
+  Each target writes the paper: the PDF and the layout draw on it, HTML writes an `@page` size and per-side margin, and DOCX writes `pgSz` with `w:orient` and `pgMar` per side. XLSX writes the paper code, the orientation and each print margin. CSV withdraws all three.
+
+  The capability descriptors gain `page.size` and `page.orientation`, and both are names a document may mark `required`.
+
+  A target's margin error now reads `expected a non-negative number, or { top, right, bottom, left }, that leaves the page room`.
+
+- `params` is now what the report declares it needs, and a render may supply one.
+
+  A bare value under `params` still **is** the parameter's value, so a document of constants reads the way it always did:
+
+  ```jsonc
+  { "params": { "year": 2025, "branded": true } }
+  ```
+
+  A plain object is a **declaration** instead, closed at `default` and `type`:
+
+  ```jsonc
+  {
+    "params": {
+      "year": { "type": "number", "default": 2025 },
+      "region": { "type": "string" }
+    }
+  }
+  ```
+
+  `type` names a JSON kind — `string`, `number`, `boolean`, `array`, `object` — because a parameter is a JSON value. There is no `date` and no `enum`.
+
+  **`default` absent makes the parameter required.** The engine rejects a render that supplies no value for it, before any expression runs. That is the main thing declaring buys: a report that states what it needs hears about it when a render does not bring it.
+
+  A host supplies values as the last argument to `render` and to `stream`:
+
+  ```js
+  await report.render(html(), data, { region: "EU" });
+  ```
+
+  Only a declared key may be supplied, a supplied value answers to the declared `type`, and values stay JSON and deep-frozen — now per render rather than once at compile.
+
+  **One kind of document changes meaning.** The engine reads an object-valued parameter as a declaration, so a document that wrote one for its value wraps it:
+
+  ```jsonc
+  { "params": { "config": { "default": { "retries": 3 } } } }
+  ```
+
+  An empty object is the sharpest case. `{ "config": {} }` now declares a parameter with no default, so every render of that document is refused until one supplies a value, or until the document wraps it.
+
+  Nothing else moves. A bare string, number, boolean or array is untouched.
+
+  A declaration may also carry a `label`, the text a person reads for the parameter. A labelled parameter is one a person supplies, so a host panel shows only those. The engine never renders a label.
+
+  A `null` default beside a `type` makes a typed parameter optional, and a render may then supply `null`:
+
+  ```jsonc
+  { "params": { "branch": { "type": "string", "default": null, "label": "Branch" } } }
+  ```
+
+  A host reads what a document declares from `report.params` and from `plan(...).params`: one frozen `{ name, required, type?, default?, label? }` per parameter, in declaration order. A plan carries them whether or not the document compiled, so an editor can render a panel beside the problems.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -70,8 +70,8 @@ key verification as `{ licensed, licensee?, id? }`.
 
 ### `report(schema, functions?)`
 
-Compiles a report and returns the compiled report. `stream(data)` is the raw event generator.
-`render(target, data)` takes a self-naming `{ name, compile }` object from a target factory
+Compiles a report and returns the compiled report. `stream(data, params)` is the raw event generator, and `params` are the values this render supplies for what the document declares.
+`render(target, data, params)` takes a self-naming `{ name, compile }` object from a target factory
 (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
@@ -209,6 +209,33 @@ validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
 `report()` throws on the first problem instead. Validation and compilation share one traversal,
 so `validate()` can never disagree with what `report()` accepts.
 
+### JSON Schema
+
+The package ships a JSON Schema of the report document. Point `$schema` at the installed copy,
+and your editor checks the document and shows the documentation for each key:
+
+```json
+{
+  "$schema": "./node_modules/quario/lib/schema.json",
+  "data": "$.orders[*]",
+  "detail": [{ "type": "text", "value": "{{ @.product }}" }]
+}
+```
+
+The path is relative to the report file. The engine accepts the `$schema` key and does not read
+it.
+
+Code reads the same file through the package export:
+
+```js
+import schema from "quario/schema.json" with { type: "json" };
+```
+
+The JSON Schema proves the shape of each value. It does not replace `validate()`. Rules that
+join two or more values, and every expression and template, stay with `validate()`. Use the
+JSON Schema to constrain what an editor or a model writes. Use `validate()` to accept a
+document.
+
 ### `quario().plan(schema, functions?, { targets }?)`
 
 The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns

package/lib/index.d.ts

@@ -12,7 +12,46 @@ import type {
 export type { QueryPath } from "padvinder";
 
 export type FunctionRegistry = Record<string, (...args: any[]) => any>;
-export type ExpressionValue<T = unknown> = T | `=${string}`;
+// Named so its pattern reaches every field that takes an expression, which is
+// how the generated JSON Schema tells an expression from a literal.
+/**
+ * An `=` expression: xprsn source after the leading `=`.
+ *
+ * @pattern ^=
+ */
+export type Expression = `=${string}`;
+export type ExpressionValue<T = unknown> = T | Expression;
+
+// The literal shapes the traversal checks one value at a time, named so each
+// carries its rule as a tag. TypeScript reads each as the plain type. The tags
+// are for the JSON Schema generated from this file (`lib/schema.json`), which
+// holds each one to the check it mirrors in `style.js` or `plan.js`.
+
+/** `#rgb` or `#rrggbb`. @pattern ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ */
+type Color = string;
+/** A three-letter ISO 4217 code, by shape. @pattern ^[A-Z]{3}$ */
+type CurrencyCode = string;
+/** @minLength 1 */
+type NonEmpty = string;
+/** Points, zero or more. @minimum 0 */
+type Points = number;
+/** Points, more than zero. @exclusiveMinimum 0 */
+type PositivePoints = number;
+/** A share of the width, in percent. @exclusiveMinimum 0 @maximum 100 */
+type WidthShare = number;
+/** @asType integer @minimum 1 */
+type Count = number;
+/** @asType integer @minimum 2 */
+type ColumnCount = number;
+/** @asType integer @minimum 0 @maximum 20 */
+type Digits = number;
+/** @minItems 1 */
+type StyledRuns = StyledRun[];
+/**
+ * A parameter's value when it is not a declaration: any JSON value but a plain
+ * object, which `params` reads as a declaration.
+ */
+type ParamValue = null | boolean | number | string | JsonValue[];
 export type ReducerSpec = string;
 
 /**
@@ -50,16 +89,16 @@ export type LineStyle = "solid" | "dashed" | "dotted";
  */
 export type BoxDeclarations = {
   /** Inset on that side, in points (>= 0). */
-  [S in Side as `padding${S}`]?: ExpressionValue<number>;
+  [S in Side as `padding${S}`]?: ExpressionValue<Points>;
 } & {
   /** Stroke width on that side, in points (>= 0). `0` is a complete side that draws nothing. */
-  [S in Side as `border${S}Width`]?: ExpressionValue<number>;
+  [S in Side as `border${S}Width`]?: ExpressionValue<Points>;
 } & {
   /** Line style of that side. */
   [S in Side as `border${S}Style`]?: ExpressionValue<LineStyle>;
 } & {
   /** Stroke color of that side, `#rgb`/`#rrggbb`. */
-  [S in Side as `border${S}Color`]?: ExpressionValue<string>;
+  [S in Side as `border${S}Color`]?: ExpressionValue<Color>;
 };
 
 /**
@@ -72,9 +111,9 @@ export type BoxDeclarations = {
  */
 export interface StyleDeclarations extends BoxDeclarations {
   /** `'sans'` | `'serif'` | `'mono'`, or an embedded font family name. */
-  family?: ExpressionValue<string>;
+  family?: ExpressionValue<NonEmpty>;
   /** Font size in points. */
-  size?: ExpressionValue<number>;
+  size?: ExpressionValue<PositivePoints>;
   bold?: ExpressionValue<boolean>;
   italic?: ExpressionValue<boolean>;
   underline?: ExpressionValue<boolean>;
@@ -82,9 +121,9 @@ export interface StyleDeclarations extends BoxDeclarations {
   /** Render the text in capitals. Capitals, not small caps. */
   uppercase?: ExpressionValue<boolean>;
   /** Text color, `#rgb`/`#rrggbb`. */
-  color?: ExpressionValue<string>;
+  color?: ExpressionValue<Color>;
   /** Background color, `#rgb`/`#rrggbb`. */
-  background?: ExpressionValue<string>;
+  background?: ExpressionValue<Color>;
   /** Horizontal alignment within the cell. */
   align?: ExpressionValue<Align>;
   /**
@@ -107,7 +146,7 @@ export interface StyleDeclarations extends BoxDeclarations {
    * the cell's own answer still, so the cell presents as display text rather
    * than falling back to the instance's currency. Unread without the kind.
    */
-  currency?: ExpressionValue<string>;
+  currency?: ExpressionValue<CurrencyCode>;
   /**
    * Where this cell's text points: a URL, or `#` and a group's `label` for a
    * destination inside the document. The one declaration the engine judges
@@ -115,15 +154,15 @@ export interface StyleDeclarations extends BoxDeclarations {
    * allowlist before it crosses, and a refused value is omitted, so the text
    * renders and the link does not. A table row refuses it.
    */
-  href?: ExpressionValue<string>;
+  href?: ExpressionValue<NonEmpty>;
   /** Blank space before this item, in points. */
-  spaceBefore?: ExpressionValue<number>;
+  spaceBefore?: ExpressionValue<Points>;
   /** Blank space after this item, in points. */
-  spaceAfter?: ExpressionValue<number>;
+  spaceAfter?: ExpressionValue<Points>;
 }
 
 export interface SortKey {
-  by: `=${string}`;
+  by: Expression;
   dir?: "asc" | "desc";
 }
 
@@ -135,7 +174,7 @@ export interface SortKey {
 export const RUN_STYLE_NAMES: readonly string[];
 
 /**
- * The names a [report default](../../../SCHEMA.md#style-declarations) may
+ * The names a [report default](https://getquario.com/docs/reference/style-declarations) may
  * declare, in the vocabulary's own order. A tool that offers them — the
  * editor's Document panel — reads this rather than keeping a copy.
  */
@@ -149,7 +188,7 @@ export const REPORT_STYLE_NAMES: readonly string[];
 export const ZERO_DASH: string;
 
 /**
- * The declarations a document may mark [`required`](../../../SCHEMA.md#validation),
+ * The declarations a document may mark [`required`](https://getquario.com/docs/diving-deeper/validating),
  * in the order the support matrix states them. Every published target's
  * `capabilities` descriptor answers for exactly these, which is what makes a
  * marking checkable.
@@ -159,7 +198,7 @@ export const REQUIRABLE: readonly string[];
 /**
  * The same names as a type, so a marking no target could answer for is an
  * error where an author writes it rather than a
- * [`plan`](../../../SCHEMA.md#validation) problem after the fact. This
+ * [`plan`](https://getquario.com/docs/diving-deeper/validating) problem after the fact. This
  * package's suite holds the two to each other in both directions, so neither
  * can gain a name the other lacks.
  */
@@ -169,6 +208,8 @@ export type RequirableName =
   | "break"
   | "reset"
   | "page.margin"
+  | "page.size"
+  | "page.orientation"
   | "header.height"
   | "groups"
   | "label"
@@ -225,7 +266,7 @@ export interface StyledRun {
  * cell written as one template string is one run, so a one-run array says
  * exactly what that string says.
  */
-export type CellValue = string | StyledRun[];
+export type CellValue = string | StyledRuns;
 
 export type Align = "left" | "center" | "right";
 export type VAlign = "top" | "middle" | "bottom";
@@ -252,7 +293,7 @@ export type FormatDeclaration =
   | FormatKind
   | {
       kind: "number" | "currency" | "percent";
-      digits?: number;
+      digits?: Digits;
       negative?: NegativeReading;
       zero?: ZeroReading;
     }
@@ -315,7 +356,7 @@ export type ReportStyleDeclarations = Pick<StyleDeclarations, "family" | "size">
  */
 export interface ImageItem {
   type: "image";
-  source: `=${string}`;
+  source: Expression;
   /** Defaults to `"natural"`. */
   fit?: ImageFit;
   /**
@@ -381,7 +422,7 @@ export type SplitSlot = (
   | (Omit<ImageItem, "style"> & { style?: SlotImageStyleDeclarations })
 ) & {
   /** Slot width as a percentage of the content width (0 < width <= 100). */
-  width?: number;
+  width?: WidthShare;
 };
 
 /**
@@ -397,8 +438,50 @@ export interface SplitItem {
   style?: StyleDeclarations;
 }
 
-/** One item in a band: text, an image, or a split. Future types may be additive. */
-export type Item = TextItem | ImageItem | SplitItem;
+/**
+ * One slot of a grid row: a split slot less `width`, which the slot takes
+ * from its column.
+ */
+export type GridSlot =
+  | (Omit<TextItem, "style"> & { style?: SlotStyleDeclarations })
+  | (Omit<ImageItem, "style"> & { style?: SlotImageStyleDeclarations });
+
+/**
+ * One column of a grid: the width share every row's slot in this position
+ * takes, and the declarations each of those slots layers its own over.
+ */
+export interface GridColumn {
+  /** Column width as a percentage of the content width (0 < width <= 100). */
+  width?: WidthShare;
+  style?: SlotStyleDeclarations;
+}
+
+/**
+ * One line on a grid's geometry: a split without `type`. A row naming fewer
+ * slots than the grid has columns leaves the rest empty, so `{}` is a
+ * spacer line of the row's size.
+ */
+export interface GridRow {
+  slots?: GridSlot[];
+  visible?: ExpressionValue<boolean>;
+  style?: StyleDeclarations;
+}
+
+/**
+ * Splits that share one column geometry: the widths, and each column's
+ * style, are stated once and every row is laid on them. Every rule a split
+ * has, a row has — full content width, no nesting, never broken across a
+ * page — and each row crosses the event stream as the split bracket it is.
+ */
+export interface GridItem {
+  type: "grid";
+  columns: [GridColumn, GridColumn, ...GridColumn[]];
+  rows: [GridRow, ...GridRow[]];
+  visible?: ExpressionValue<boolean>;
+}
+
+/** One item in a band: text, an image, a split, or a grid. Future types may be additive. */
+export type Item = TextItem | ImageItem | SplitItem | GridItem;
 
 export interface TableHeader {
   value: CellValue;
@@ -408,7 +491,7 @@ export interface TableHeader {
    * How many columns this header covers — a literal integer >= 1, never an
    * expression; absent is 1. The columns it covers omit their own `header`.
    */
-  span?: number;
+  span?: Count;
 }
 
 export interface TableColumn extends Omit<Cell, "style"> {
@@ -420,7 +503,7 @@ export interface TableColumn extends Omit<Cell, "style"> {
    */
   header?: string | TableHeader;
   /** Column width as a percentage of the table width (0 < width <= 100). */
-  width?: number;
+  width?: WidthShare;
 }
 
 export interface TableRow {
@@ -439,7 +522,7 @@ export type TotalCell = Omit<Cell, "style"> & {
    * How many columns this cell covers — a literal integer >= 1, never an
    * expression; absent is 1.
    */
-  span?: number;
+  span?: Count;
 };
 
 export interface TotalRow {
@@ -476,7 +559,7 @@ export interface TableDetail {
 
 export interface Group {
   name: string;
-  by: `=${string}`;
+  by: Expression;
   /**
    * This instance's name for **navigation** rather than for the page: one
    * template, resolved once per instance in group scope, where the handle and
@@ -490,7 +573,7 @@ export interface Group {
    * and the content between them does not. A target with a way to hide a row
    * and keep it -- the worksheet -- hides those rows, where a reader opens the
    * group again. The rest drop them, and the
-   * [matrix](../../../SCHEMA.md#what-each-target-makes-of-a-declaration) says
+   * [matrix](https://getquario.com/docs/reference/support-matrix) says
    * which does which.
    */
   collapsed?: boolean;
@@ -509,13 +592,13 @@ export interface Group {
    * Flow each instance's content in this many page columns (integer >= 2).
    * Columned regions cannot nest.
    */
-  columns?: number;
+  columns?: ColumnCount;
   sort?: SortKey[];
   /**
    * Keep this many rows after this group's `sort`. Integer >= 1. Rows past
    * the count are dropped from aggregates and runners, unlike `visible`.
    */
-  take?: number;
+  take?: Count;
   aggregates?: Record<string, ReducerSpec>;
   /** Running accumulators, read as `run.<name>` on detail rows. */
   run?: Record<string, ReducerSpec>;
@@ -531,15 +614,81 @@ export interface Group {
 export interface PageBands {
   header?: Item[];
   footer?: Item[];
-  /** Inset on all four sides, in points. Required when the report header declares `height`. */
-  margin?: number;
+  /**
+   * The inset from the paper's edge, in points: one number for all four
+   * sides, or each side named. Required when the report header declares
+   * `height`. A target's own `margin` option applies where this is absent,
+   * and declaring both is a render error.
+   */
+  margin?: Points | PageMargin;
+  /**
+   * The report's paper, by name. A `[width, height]` pair is a target option
+   * only. A target's own `size` option applies where this is absent, and
+   * declaring both is a render error.
+   */
+  size?: PaperName;
+  /** Which way the paper is turned. */
+  orientation?: Orientation;
+}
+
+/** A margin that names each side, in points. All four are required. */
+export interface PageMargin {
+  top: Points;
+  right: Points;
+  bottom: Points;
+  left: Points;
+}
+
+/** The named paper sizes a document may declare. */
+export type PaperName = "A4" | "letter";
+
+/** Which way the paper is turned. */
+export type Orientation = "portrait" | "landscape";
+
+/**
+ * What a report declares it needs. A bare value under `params` *is* the
+ * parameter's value; a plain object is a declaration. `default` absent means
+ * the parameter is required, and a render that supplies none is rejected
+ * before any expression runs. `type` names a JSON kind, because a parameter
+ * is a JSON value. A `null` default beside a `type` makes the parameter
+ * optional and lets a render supply `null`.
+ */
+export interface ParamDeclaration {
+  default?: JsonValue;
+  type?: ParamType;
+  /**
+   * The text a person reads for this parameter. A parameter with a label is
+   * one a person supplies; the engine never renders it.
+   */
+  label?: string;
+}
+
+export type ParamType = "string" | "number" | "boolean" | "array" | "object";
+
+/**
+ * One declared parameter, as a host reads it: the surface a parameter panel
+ * asks what to render. `type`, `default` and `label` are present only where
+ * the document wrote one, and `required` is the absence of a default.
+ */
+export interface DeclaredParam {
+  readonly name: string;
+  readonly required: boolean;
+  readonly type?: ParamType;
+  readonly default?: JsonValue;
+  /** Present where the document wrote one: a person supplies this parameter. */
+  readonly label?: string;
 }
 
 export interface ReportSchema {
-  params?: Record<string, JsonValue>;
+  /**
+   * Where an editor finds this document's JSON Schema. The engine checks that
+   * it is a string and reads nothing else.
+   */
+  $schema?: string;
+  params?: Record<string, ParamValue | ParamDeclaration>;
   /**
    * The declarations this document cannot do without, each marked `true`.
-   * Only [`plan`](../../../SCHEMA.md#validation) reads it, against the target
+   * Only [`plan`](https://getquario.com/docs/diving-deeper/validating) reads it, against the target
    * descriptors its caller names: every required declaration one of them
    * withdraws or leaves unread becomes a problem of its own at
    * `required.<name>`, which nulls the report as any other problem does. No
@@ -547,13 +696,13 @@ export interface ReportSchema {
    */
   required?: Partial<Record<RequirableName, true>>;
   data: string;
-  where?: `=${string}`;
+  where?: Expression;
   sort?: SortKey[];
   /**
    * Keep this many rows after the report `sort`. Integer >= 1. Rows past the
    * count are dropped from aggregates and runners, unlike `visible`.
    */
-  take?: number;
+  take?: Count;
   aggregates?: Record<string, ReducerSpec>;
   /** Running accumulators, read as `run.<name>` on detail rows. */
   run?: Record<string, ReducerSpec>;
@@ -567,13 +716,13 @@ export interface ReportSchema {
    * Dual-shaped like `detail`: an item array, or `{ height, items }` when the
    * header pins a flow box from the page top.
    */
-  header?: Item[] | { height: number; items: Item[] };
+  header?: Item[] | { height: PositivePoints; items: Item[] };
   empty?: Item[];
   /**
    * Flow the report body in this many page columns (integer >= 2). Columned
    * regions cannot nest.
    */
-  columns?: number;
+  columns?: ColumnCount;
   groups?: Group[];
   detail?: Item[] | TableDetail;
   footer?: Item[];
@@ -601,8 +750,8 @@ export interface QuarioOptions {
   /**
    * License key (LICENSE section 6). Verified offline once, when the instance
    * is created; `license` settles with the result. Without a key, or with one
-   * whose validity window does not cover this version's release date, every
-   * report this instance compiles marks its output as unlicensed.
+   * that ends before this version's release date, every report this instance
+   * compiles marks its output as unlicensed.
    */
   license?: string;
   /** Locale for `format`. Defaults to `"en-US"` when a kind is presented. */
@@ -755,8 +904,12 @@ export interface ReportStartEvent {
    * states it so no target has to know it.
    */
   marking?: string;
-  /** The document's `page.margin`, when declared. */
-  margin?: number;
+  /** The document's `page.margin`, when declared, in the shape the author wrote it. */
+  margin?: number | PageMargin;
+  /** The document's `page.size`, when declared. */
+  size?: PaperName;
+  /** The document's `page.orientation`, when declared. */
+  orientation?: Orientation;
   /** The report header's authored `height`, when the object form is used. */
   headerHeight?: number;
   /** Present when the instance was constructed with `locale`. */
@@ -953,7 +1106,7 @@ export type WalkEvent = ReportEvent | SplitEvent;
 export function splits(events: Iterable<ReportEvent>): Generator<WalkEvent, void>;
 
 /**
- * Each [collapsed](../../../SCHEMA.md#group-definition) instance shut: its
+ * Each [collapsed](https://getquario.com/docs/reference/report-schema#group) instance shut: its
  * brackets and its own header and footer items survive, and everything
  * between them is dropped, nested instances whole.
  *
@@ -1010,7 +1163,11 @@ export interface QuarioDiagnostic extends Error {
 /** The compiled report: `stream` plus its metadata, rendered per target. */
 export interface CompiledReport {
   /** The raw event seam: one generator of report events per call. */
-  stream(data?: unknown): Generator<ReportEvent, void, undefined>;
+  stream(
+    data?: unknown,
+    params?: Readonly<Record<string, JsonValue>>,
+  ): Generator<ReportEvent, void, undefined>;
+  readonly params: readonly DeclaredParam[];
   readonly names: readonly string[];
   readonly functions: readonly FunctionSignature[];
   readonly paths: readonly QueryPath[];
@@ -1019,7 +1176,11 @@ export interface CompiledReport {
    * output, whether the target renders synchronously or not; target shape
    * problems throw synchronously as definition errors.
    */
-  render<Out>(target: Target<string, Out>, data?: unknown): Promise<Awaited<Out>>;
+  render<Out>(
+    target: Target<string, Out>,
+    data?: unknown,
+    params?: Readonly<Record<string, JsonValue>>,
+  ): Promise<Awaited<Out>>;
 }
 
 /**
@@ -1083,6 +1244,7 @@ export interface PlanOptions {
 
 export interface Plan {
   readonly report: CompiledReport | null;
+  readonly params: readonly DeclaredParam[];
   readonly problems: readonly Problem[];
   readonly anchors: Readonly<Record<string, readonly string[]>>;
   readonly warnings: readonly Warning[];