quario 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable changes to quario are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-01
+
+### Added
+
+- **A report default: one `style` block for the whole document.** A top-level
+  `style` beside `header`/`detail`/`footer` states the typeface a report is set
+  in, so a document with one face names it once instead of on every item, every
+  table column, every header and every total cell. It takes `family` and
+  `size`; any other declaration there is a located definition error, exactly as
+  a text declaration on an image item is. Values are literals or `=`
+  expressions like any other style block's, resolved once per render in report
+  scope.
+
+- **`report-start` carries the resolved report default as `style`.** A
+  report-level fact, never merged into an item's own `style`: an event's
+  `style` stays what the author wrote on that node, and a consumer composes the
+  default itself, once — under its own band-role defaults and under every
+  event's own style. Absent when the report declares none, so a consumer
+  written before this field renders in its own baseline exactly as it did.
+
+- **An `uppercase` style declaration.** A boolean beside `bold` and `italic`,
+  literal or an `=` expression, for the capitalised column labels business
+  forms are usually set with. It is capitals, not small caps — real small caps
+  need a font feature the PDF target's built-in faces cannot supply, so the
+  declaration promises only what every target can draw. Image items keep
+  refusing it, as they refuse every text declaration.
+
+- **A `split` item places values across the line instead of down the band.**
+  The invoice header's "seller left, customer right", which a band could not
+  say before. `{ "type": "split", "slots": [...] }` takes two or more slots,
+  each an ordinary `text` or `image` item plus an optional `width` percentage
+  under the same rules a table column's obeys; width-less slots divide what
+  the sized ones leave, evenly. A split is always the full content width and
+  never nests — it says what sits beside what, never where anything is — and
+  a slot that renders nothing keeps its width, so a line's geometry never
+  moves with the data. Splits may appear in every item array except table and
+  total cells.
+
+- **`split-start` / `split-end` bracket a split's slots on the event stream.**
+  `split-start` carries the slot geometry, then one ordinary `item` or `image`
+  event per slot in order, then `split-end`. Existing consumers need no
+  change: the walk driver's missing-handler rule means a target that ignores
+  the bracket still receives the slot items and renders them stacked.
+
+- **`quario().plan(schema, funcs?)` hands the whole traversal over at once.**
+  Returns `{ report, problems, anchors }` from one descent: the compiled
+  report (`null` while the document has problems), every problem as
+  `{ path, source?, message, diagnostic? }`, and a map from each compiled
+  source's schema path to the anchors and group handles it reads. A host that
+  validates and renders per edit — an editor — pays one traversal instead of
+  two, can point at a problem in its own UI without parsing a message apart,
+  and can tell where a node may safely move. `validate()` is unchanged: its
+  strings are those problems' `message` fields.
+- **Every problem keeps its own located diagnostic.** `validate()` retained
+  `start`/`end` offsets on at most one problem per document; the structured
+  list carries each problem's own, so a consumer can underline the offending
+  character in every faulty expression rather than only the first.
+- **Events name the definition behind them.** `item`, `image` and
+  `group-start` events carry `path`, the schema path of the node that
+  produced them; `table-start` carries `detail` and its columns their own,
+  and every table cell carries its column definition's path (a total cell its
+  `detail.total[i]` entry). Rows carry no identity — a row is data, not
+  schema. Additive: a consumer that ignores the field is unaffected.
+- **`display(value)` joins one value the way `text()` does.** The scalar
+  display rule behind the token join, re-exported beside `text()` so a stream
+  consumer that stringifies token values itself renders exactly what the
+  official targets render — Dates included.
+
+- **`maxDepth: Infinity` opts a query budget out.** The data query's traversal
+  budgets accept an explicit `Infinity` per key for "this budget, unbounded".
+  The 500-deep default is unchanged — it is now padvinder's own, applied for
+  every consumer rather than added by quario at the seam.
+
+- **Located data-query errors carry padvinder's code and span.** A `data`
+  query that does not parse now surfaces with padvinder's `code` and
+  `start`/`end` offsets into the query you wrote — filter faults included —
+  alongside the band/item path quario already attached. The code names the
+  category of mistake: `PADVINDER_MISSING_ROOT`, `PADVINDER_BAD_SELECTOR`,
+  `PADVINDER_UNCLOSED_BRACKET`, `PADVINDER_BAD_STRING`,
+  `PADVINDER_UNKNOWN_FUNCTION`, or `PADVINDER_SYNTAX` for a path character or
+  filter body that is open-endedly not a query. Traversal budgets exceeded at
+  render time keep `limit`/`actual` and carry no span.
+
+### Changed
+
+- **Cells render straight over the engine scope chain.** A text cell no longer
+  allocates a wrapper scope and an anchor pair per cell per row — quario's
+  chain already binds `$` at the render base and `@` on the detail row, and
+  sjabloon now renders over it as-is. A 4-column stream over a million rows
+  went from 1.7s to 0.5s. No report changes what it renders. Requires
+  sjabloon 0.11.
+
+- **A compiled report's `functions` carry signatures.** Each entry is now
+  `{ name, arity, doc? }` instead of a bare name — `arity` from the function's
+  declared parameter count (or its own numeric `arity` where rest parameters
+  mislead `length`), `doc` from an own `doc` string when it carries one — in
+  the same call-first-seen order. `names` is unchanged. Requires xprsn 0.11
+  and sjabloon 0.11.
+
+- **A bare `Date` renders as ISO 8601 UTC, the same on every machine.**
+  Display text for a `Date` value was `String(date)`, which bakes the
+  rendering host's timezone and locale into the output — so one report
+  produced different bytes on different machines. Every target now renders a
+  valid `Date` as its `toISOString()` form through the one shared display
+  rule; an invalid `Date` keeps its deterministic `Invalid Date` text.
+  Reports that want a formatted date keep using a registered function,
+  exactly as before.
+
+- **A bad literal pattern in the data query is a definition error.** A typo'd
+  I-Regexp written as a string literal in `match()`/`search()` used to
+  produce a plausible empty report with no signal; `report()` and
+  `validate()` now surface it at compile time as a located error, with
+  offsets at the pattern literal in the query. The class and `code` are
+  treffer's — a malformed pattern is a `SyntaxError` with `TREFFER_SYNTAX`,
+  one past treffer's limits a `RangeError` with a `TREFFER_MAX_*` code and
+  `limit`/`actual` — on the same rule that already gives xprsn's codes to a
+  fault in an expression: the engine that decided the fault names it. A
+  pattern that arrives from render data keeps RFC 9535 semantics and still
+  matches nothing at render time. Requires padvinder 0.8.
+
+- **Each engine relocates its own diagnostic.** A located error is now a copy
+  made by the engine that raised it (xprsn, sjabloon, or padvinder), so it
+  carries every field that engine puts on a diagnostic — nothing is lost in
+  quario's re-throw, today or when an engine adds a field — and it still
+  passes that engine's own `isDiagnostic`. Host errors are wrapped as plain
+  errors with no diagnostic metadata, exactly as before. Requires xprsn 0.10,
+  sjabloon 0.9, and padvinder 0.5. No report changes what it renders.
+
+### Fixed
+
+- **A host error cannot pose as the report's diagnostic.** `report()` rethrows
+  the first definition problem's located engine error; it chose that error by
+  probing for a `code` property, so a host error class that stamps `code` on
+  itself in its constructor was rethrown as if the engines had raised it. The
+  choice now goes through the same identity-based authentication as
+  `isDiagnostic`; everything else falls back to a plain `SyntaxError` naming
+  the first problem, as before.
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- **A compile-once report engine.** You hand it a JSON report definition and
+  data; it plans once and streams render events that every target consumes.
+  Text cells go through sjabloon, everything else through xprsn, rows through
+  padvinder. Unlicensed output carries a marking on the opening event; each
+  target only decides where that wording goes.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -1 +1,237 @@
-quario — in the makings, not yet released.
+# quario
+
+**The report engine.** Turns a JSON report definition plus data into a stream of structured render
+events. Every render target ([`@quario/html`](https://www.npmjs.com/package/@quario/html),
+[`@quario/pdf`](https://www.npmjs.com/package/@quario/pdf),
+[`@quario/xlsx`](https://www.npmjs.com/package/@quario/xlsx),
+[`@quario/csv`](https://www.npmjs.com/package/@quario/csv), or your own) consumes that
+stream.
+
+The engine does not escape text, emit HTML, or format pages or cells. Install a target when you
+want output. Use this package when you want to _build_ a target, or to consume report structure
+as data.
+
+## Install
+
+```bash
+npm install quario
+```
+
+ESM-only, Node 22+. Dependencies: [xprsn](https://github.com/getquario/xprsn) (expressions),
+[sjabloon](https://github.com/getquario/sjabloon) (templates),
+[padvinder](https://github.com/getquario/padvinder) (JSONPath).
+
+## Quick start
+
+```js
+import { quario, text } from "quario";
+
+const schema = {
+  data: "$.orders[*]",
+  aggregates: { total: "sum:=@.price * @.qty" },
+  detail: [{ type: "text", value: "{{ @.product }} — {{ @.price * @.qty }}" }],
+  footer: [{ type: "text", value: "Total {{ $.total }}" }],
+};
+
+const report = quario().report(schema);
+
+for (const e of report.stream({ orders: [{ product: "Desk", price: 250, qty: 2 }] })) {
+  if (e.type === "item") console.log(e.role, text(e.tokens));
+}
+// detail       Desk — 500
+// report-footer Total 500
+```
+
+`report()` compiles the definition **once** into a tree of closures. You render the compiled
+report per dataset with `report.render(target, data)`, passing the target and its configuration
+at the call, so one compile serves any number of target configurations. Definition errors
+surface at compile time, so compile at startup and render in your request path.
+
+## API
+
+### `quario(options?)`
+
+Creates a configured instance with host-level controls: `{ query?, license? }`. Returns
+`{ report, license }`. `license` settles with this instance's 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
+(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 at compile time, like any other definition error.
+
+The data pre-pass (select, filter, sort, aggregate) runs when you call the renderer, because a
+report header may interpolate a report aggregate. Event emission pulls on demand, so a consumer
+that stops early does not pay for the rest of the walk.
+
+The compiled report carries metadata:
+
+```js
+report.names; // free variable names the expressions read, excluding engine anchors
+report.functions; // registry function names the definition calls
+report.paths; // padvinder's deeply frozen dependency topology for the `data` query
+```
+
+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
+row, an optional `total-row`, and `table-end`.
+
+| Event          | Carries                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| `report-start` | `params`, resolved report `aggregates`, optional `page` band closures, `columns`, `marking` |
+| `item`         | `role`, `path`, `tokens`, optional `style`, `run`                                           |
+| `image`        | `role`, `path`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`  |
+| `group-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `reset`, `columns`          |
+| `group-end`    | `name`, `depth`                                                                             |
+| `table-start`  | `path`, `columns` (each `header`, `path`, optional `width`)                                 |
+| `row`          | `cells`, optional `style`, `run`                                                            |
+| `total-row`    | `cells`                                                                                     |
+| `table-end`    | -                                                                                           |
+| `report-end`   | -                                                                                           |
+
+**Cells carry tokens.** A cell is `{ tokens, style? }`. Each token is either `{ literal }`
+(static template text, verbatim) or `{ value }` (one interpolation's _pre-format_ value, the
+expression result before any stringification). This is the typed seam: a cell whose template is `{{ @.amount }}` holds one value token with the
+number itself, so a spreadsheet consumer writes a real numeric cell. `Total: {{ @.amount }}` mixes
+a literal and a value, so the cell is text only.
+
+**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
+author its wording. **`columns`** on `report-start` / `group-start` is the declared
+page column count when present. No shipped target honors it yet;
+xlsx never will.
+
+### `text(tokens)`
+
+Joins a token stream to display text: literals verbatim, values as `String(value ?? "")`, run
+styles ignored. Re-exported from sjabloon so consumers do not hand-roll the join.
+
+### `typed(tokens)`
+
+Exactly one value token holding a finite number, a boolean, or a valid `Date` keeps that
+pre-stringify value. Anything else, including a lone null, reports `undefined` and joins to
+display text. Spreadsheet consumers use this for real numeric cells;
+[`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
+
+### `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
+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
+calls it for you.
+
+### `validate(schema, functions?)`
+
+Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
+empty array means valid.
+
+```js
+validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
+// ['sort[0].dir: unknown sort direction "up"']
+```
+
+`report()` throws on the first problem instead. Validation and compilation share one traversal,
+so `validate()` can never disagree with what `report()` accepts.
+
+### `quario().plan(schema, functions?)`
+
+The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns
+`{ report, problems, anchors }`: the compiled report (`null` while the document has problems),
+every problem structurally as `{ path, source?, message, diagnostic? }` (the `message` is exactly
+`validate()`'s string, and every problem keeps its own located diagnostic with `start`/`end`
+offsets, not only the first), and `anchors`, mapping each compiled source's schema path to the
+anchors and group handles it reads — the unfiltered complement of `names`.
+
+```js
+const { report, problems, anchors } = quario().plan(schema);
+if (report) await report.render(html(), data);
+else console.error(problems[0].path, problems[0].message);
+```
+
+### `isDiagnostic(error)`
+
+True when a caught value is one of the stack's located errors: quario's own, or one thrown
+directly by xprsn, sjabloon, or padvinder. Authentication checks identity. An error that only
+matches the shape does not pass.
+
+Located errors name their band path and offending source while keeping their original type
+(`SyntaxError`, `TypeError`, `RangeError`). They carry `code`, `start`/`end` offsets, and (for
+query budget failures) `limit` and `actual`.
+
+```js
+try {
+  await renderer(data);
+} catch (e) {
+  if (isDiagnostic(e)) console.error("report problem:", e.message);
+  else throw e; // one of your own functions failed
+}
+```
+
+## The scope model
+
+| Anchor        | Is                                                                  |
+| ------------- | ------------------------------------------------------------------- |
+| `@`           | The current row. Unbound outside detail rows, so `@.x` throws there |
+| `$`           | The report root: `$.input`, `$.params`, and report aggregates       |
+| `<groupName>` | A named handle per enclosing group: `.key` plus its aggregates      |
+| `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 `?.`.
+
+## Options
+
+```js
+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
+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.
+
+Two rules a target owes its users: escape or neutralize every `value` token at your own edge, and
+map the style vocabulary to your own formatting model rather than expecting CSS.
+
+The stream is additive. The walk driver skips any event you register no handler for, so a target
+that ignores a newer event (for example, `example/markdown.js` has none for `image`) keeps rendering
+when a schema uses one.
+
+A target that runs a loop of its own can `await breathe()` between batches to hand the event loop
+back, as `walk` does for the targets that drive through it.
+
+## Content Security Policy
+
+Expressions and templates compile to closures. There is no string-to-code path anywhere in this
+package, so it runs under a script policy that omits `unsafe-eval`. The test suite enforces it
+under Node's `--disallow-code-generation-from-strings` flag, a source scan, and a Playwright
+harness that loads the published files under a strict CSP.
+
+## License
+
+Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
+licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+
+Pass your license key in the options; it is verified offline:
+
+```js
+const q = quario({ license: "quario_..." });
+await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
+```