quario 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # quario
 
+## 0.9.0
+
+### Minor Changes
+
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
+
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
+
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+### Patch Changes
+
+- The engine verifies a license key against a new signing key.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -63,7 +63,7 @@ Compiles a report and returns the compiled report. `stream(data)` is the raw eve
 (e.g. `html()` from `@quario/html`) or your own.
 
 A render is async: quario awaits key verification before the target sees its first event. A
-malformed target throws synchronously from `render`, before the first event; definition problems
+malformed target throws synchronously from `render`, before the first event. Definition problems
 throw earlier, at `report()`.
 
 The data pre-pass (select, filter, sort, aggregate) runs when you call the renderer, because a
@@ -80,7 +80,7 @@ report.paths; // padvinder's deeply frozen dependency topology for the `data` qu
 
 Events arrive in render order: `report-start`, report `header` items, then either the `empty`
 items or the group/detail walk, then `footer` items, `report-end`. Group instances bracket their
-content with `group-start`/`group-end`; a table detail yields `table-start`, one `row` per visible
+content with `group-start`/`group-end`. A table detail yields `table-start`, one `row` per visible
 row, one `total-row` per emitted total row, and `table-end`.
 
 | Event          | Carries                                                                                                                                                                                                             |
@@ -88,7 +88,7 @@ row, one `total-row` per emitted total row, and `table-end`.
 | `report-start` | `params`, resolved report `aggregates`, optional `page` band closures, `columns`, `style` (the report default), `marking`, `margin`, `headerHeight`, and the instance's `locale` / `currency` / `timeZone` when set |
 | `item`         | `role`, `path`, `tokens`, optional `style`, `run`                                                                                                                                                                   |
 | `image`        | `role`, `path`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`                                                                                                                          |
-| `split-start`  | `role`, `slots` (each an optional `width`), optional `style`; one `item` or `image` per slot follows, then `split-end`                                                                                              |
+| `split-start`  | `role`, `slots` (each an optional `width`), optional `style`. One `item` or `image` per slot follows, then `split-end`                                                                                              |
 | `split-end`    | -                                                                                                                                                                                                                   |
 | `group-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `reset`, `columns`                                                                                                                                  |
 | `group-end`    | `name`, `depth`                                                                                                                                                                                                     |
@@ -108,18 +108,18 @@ a literal and a value, so the cell is text only.
 
 **A page-number token names itself.** A value token whose interpolation is exactly
 `{{ page.number }}` or `{{ page.total }}` also carries `field`, holding that same string. The
-value is the number this page was rendered with; `field` says which page value the token stands
+value is the number the render used for this page. `field` says which page value the token stands
 for, so a target whose own document format numbers pages can write its own live field there
 instead. Anything computed from them carries no `field`.
 
 **Escaping is the consumer's job.** A target that embeds values in markup must escape them at its
 own edge.
 
-**`report-start.marking`** carries the evaluation wording when the render is unlicensed, or while
-verification is still settling. Licensed streams omit it. Targets place the marking; they do not
+**`report-start.marking`** carries the evaluation wording when no license covers the render, or while
+verification is still settling. Licensed streams omit it. Targets place the marking. They do not
 author its wording. **`columns`** on `report-start` / `group-start` is the declared
 [page column](https://getquario.com/docs/diving-deeper/bands/#flowing-in-columns) count when
-present. `@quario/pdf` and `@quario/html` lay page columns out;
+present. `@quario/pdf` and `@quario/html` lay page columns out.
 xlsx never will.
 
 ### `text(tokens)`
@@ -133,7 +133,7 @@ Exactly one value token holding a finite number, a boolean, or a valid `Date` ke
 pre-stringify value. Anything else, including a lone null, reports `undefined` and joins to
 display text. Passing the cell's resolved `format` kind opts into the seam's one coercion: under
 `"date"`, an RFC 3339 string revives to the `Date` it names. Spreadsheet consumers use this for
-real numeric cells;
+real numeric cells.
 [`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
 
 ### `styledRuns(tokens)`
@@ -147,12 +147,12 @@ target cannot drift from them.
 ### `walk(events, handlers)` / `breathe()`
 
 `walk` is the delivery driver every official target uses. Pass one render's event iterable and
-per-event handlers keyed by type; a missing handler ignores that event. It pulls on demand, hands
-the loop back between batches, and delivers the opening event before pulling a second, so a
+per-event handlers keyed by type. A missing handler ignores that event. It pulls on demand,
+returns the loop between batches, and delivers the opening event before pulling a second, so a
 target can settle `report-start` (page bands, marking) there instead of draining the stream
 itself.
 
-`breathe()` is that hand-back alone. Await it between batches of a loop you own; `walk` already
+`breathe()` is that return alone. Await it between batches of a loop you own. `walk` already
 calls it for you.
 
 ### Presentation helpers
@@ -163,11 +163,11 @@ cell the same way:
 - `display(value)` — the scalar rule `text()` joins with: a `Date` as ISO 8601 UTC, nullish as
   the empty string, everything else `String(value)`.
 - `format(value, style?, options?)` — presents a token under the cell's resolved `format`
-  declaration (its kind and modifier, and for `currency` the cell's own code); `undefined` when the kind does not apply, so the caller falls back to
-  `display()`.
+  declaration (its kind and modifier, and for `currency` the cell's own code). It answers
+  `undefined` when the kind does not apply, so the caller falls back to `display()`.
 - `fractionDigits(style?, options?)` — the digit count a resolved `format` declaration presents:
   the kind's own (two for `number` and `percent`, a currency's minor units for `currency`) unless
-  the declaration's `digits` overrides it; `undefined` where there is no count.
+  the declaration's `digits` overrides it. It answers `undefined` where there is no count.
 - `currencyOf(style?, options?)` — which code a money cell wears: its own, else the instance's.
 - `isReportBand(role)` — whether a role names one of the report's own bands rather than a
   group's.
@@ -176,8 +176,8 @@ cell the same way:
 
 ### `validate(schema, functions?)`
 
-Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
-empty array means valid.
+Validates a definition without rendering it. It returns every problem as a path-prefixed string.
+An empty array means valid.
 
 ```js
 validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
@@ -202,7 +202,7 @@ is not a problem at a lower severity, which is why it has no `diagnostic` — no
 engine decided. Neither warning below locates into an authored source, so none carries a `source`
 today. **A warning is never fatal**: a document carrying only warnings compiles and
 renders, so `report` is `null` on `problems` alone. Two declarations warn today — a `currency` on
-a cell whose `format` is not `"currency"`, and a table where every column is sized and the widths
+a cell whose `format` is not `"currency"`, and a table where the author sized every column and the widths
 total under 100 — and the list is advisory and deliberately incomplete, so a quiet one is not a
 promise that every declaration will be read. `validate()` returns problems only.
 
@@ -217,10 +217,10 @@ else console.error(problems[0].path, problems[0].message);
 
 True when a caught value is a **located diagnostic**: an error xprsn, sjabloon or padvinder
 minted — thrown by that engine, or re-thrown by quario with the engine original behind it.
-Authentication checks identity. An error that only matches the shape does not pass.
+Authentication tests identity. An error that only matches the shape does not pass.
 
-Being located is not what the guard reads: quario's own verdicts on a document and a registered
-function's own throw are located too, and neither is a diagnostic. Errors a report throws
+Location is not what the guard reads: quario's own verdicts on a document and a registered
+function's own throw carry a location too, and neither is a diagnostic. Errors a report throws
 name the path they failed at — and the offending source, where there is one — while keeping their
 original type (`SyntaxError`, `TypeError`, `RangeError`). What a diagnostic adds on top is
 metadata an engine vouches for: `code`, `start`/`end` offsets, and, for a query budget in place
@@ -246,7 +246,7 @@ try {
 | `run.<name>`  | Running accumulator values on the current detail row                |
 
 Each anchor is a distinct object. Absent reads are `null`, so `x == null` holds for a missing
-field; reading _through_ a null base still throws, so use `?.`.
+field. Reading _through_ a null base still throws, so use `?.`.
 
 ## Options
 
@@ -254,15 +254,15 @@ field; reading _through_ a null base still throws, so use `?.`.
 quario({ query: { maxNodes: 10_000, maxDepth: 64, maxResults: 1_000 } }).report(schema, functions);
 ```
 
-`query` bounds the JSONPath data selection. Hosts set budgets through this API argument;
-definitions do not carry it. Failures are located at `data`, keep their `RangeError` type, and
+`query` bounds the JSONPath data selection. Hosts set budgets through this API argument.
+Definitions do not carry it. Failures point at `data`, keep their `RangeError` type, and
 carry `code`, `limit`, and `actual`. Every render starts with fresh counters.
 
 ## Writing a render target
 
 Read the stream through the public API. Do not reach for engine internals. A complete, tested
 Markdown target lives in the repository at `example/markdown.js` in about 70 lines. The built-in
-targets are written against the same public API.
+targets use the same public API.
 
 Two rules a target owes its users: escape or neutralize every `value` token at your own edge, and
 map the [style vocabulary](https://getquario.com/docs/reference/style-declarations/) to your own
@@ -291,10 +291,10 @@ the [engine reference](https://getquario.com/docs/reference/quario/) is this pac
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key in the options; it is verified offline:
+Pass your license key in the options. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/host.js

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

package/lib/index.d.ts

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

package/lib/index.js

@@ -34,6 +34,7 @@ export {
   STYLE_NAMES,
 } from "./style.js";
 export { imageError, isDiagnostic } from "./locate.js";
+export { hostMeta, hostOptions } from "./host.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */
 

package/lib/license.js

@@ -11,12 +11,12 @@
 // 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-14"; // release-date
+let RELEASE = "2026-09-15"; // 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.
 let PUBKEY =
-  "BEyXC0sH4pDoL-gGxLTqHguWi38WK2v7OrAfNvK8_4Ou8yLhcKgX5dzCoj1ojj6ez0B1cwMDPfejthqEQ4wZGjM";
+  "BLT0Rp5dYp7U6qiaBO5GfEx5lOntJZAbCrbmEfE824dHhdEzfylChU7xUEDj5jnArxSjXaTu8jnBPD8MX5FbNik";
 
 // The marking wording, stated once for the whole engine and carried to every
 // target on `report-start` (SCHEMA.md, "License keys"): the targets own where

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",