quario 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # quario
 
+## 0.11.1
+
+### Patch Changes
+
+- **The declarations now carry `href` and `schemes`.** `StyleDeclarations` states `href`, `RunStyleDeclarations` picks it up as the twelfth inline name, and `QuarioOptions` states the `schemes` allowlist beside the three names that present `format`. The engine has admitted both since 0.11.0 and `SCHEMA.md` specifies them; the published types said otherwise, so a TypeScript consumer writing a link, or the allowlist that admits one, was told it was an error. The `format` declaration's own comment said a kind carries one modifier, which stopped being true when a number kind took three. `test/types.check.ts` exercises the allowlist and both spellings of a link, since a hand-written surface drifts exactly where nothing reads it.
+
+## 0.11.0
+
+### Minor Changes
+
+- **`isBoxName(name)` is exported.** It answers whether a style name is part of the box — a padding or a border part — which is the partition the spec defines a table row's box by. A target that strips the box off a style, or a tool that lists the box names, imports it beside `STYLE_NAMES` rather than matching the two prefixes itself.
+- **A number kind reads `negative` and `zero`.** `format` gains two modifiers on `number`, `currency` and `percent`: `negative` is `"minus"` or `"parens"`, and `zero` is `"number"` or `"dash"`. Under `parens` a negative reads as its magnitude in parentheses, and under `dash` a zero reads as `-`. Both defaults are what every kind presented before, so no existing report moves. They compose with `digits`, with the percent kind's scaling and with a currency's code. A value outside either pair is a located definition error, and `date` takes neither. The resolved declaration a cell carries now states all three of a number kind's modifiers, so no consumer defaults one for itself.
+- **A group may declare `collapsed`.** One optional literal, `true` or `false`, asking that the instance open **shut**: its header and footer are shown and the content between them is not. Aggregates are untouched — the rows stay in the partition and still count, so a footer totals what nobody is shown. The `group-start` event carries it, and the new `collapse(stream)` helper is what a target with nowhere to hide a row reads the stream through: it drops a collapsed instance's content, nested instances whole, and keeps its brackets and its own bands. An expression is a located definition error.
+- **A group may declare a `label`.** One optional template beside `name` and `by`, resolved once per instance in group scope — the instance's own handle and `$` are bound, `@` is unbound as in any group band — and carried on `group-start` as the resolved text. It names the instance for navigation rather than for the page: a target with somewhere to put a navigation name spends it there, and the others withdraw it, so no page changes. A value that is not a template string is a located definition error, and a hollow instance stays unlisted whether it declares one or not.
+- **A run may carry an `href`.** The twelfth name in the styled run's inline subset, and the one declaration this engine judges rather than passes on: a URL names a location, and `javascript:` is a string-to-code path that escaping at the markup edge cannot answer. A URL is admitted before it crosses, against a host allowlist — `quario({ schemes })`, defaulting to `https:` and `mailto:` — so a target receives a URL already admitted or none at all. A refused value is omitted, so the text renders and the link does not; a URL stating no scheme is refused with the rest, because a scheme list cannot say "no scheme" without admitting `//host/path`. An `href` beginning `#` names a group's `label` and needs no allowlist. A `schemes` option the engine cannot read throws at construction rather than falling back to the default, because an allowlist quietly replaced is a host believing it restricted something it had not. A table row refuses `href`, as it refuses every declaration that presents a value.
+- **`REPORT_STYLE_NAMES`.** The two names a report default may declare, `family` and `size`, in the vocabulary's own order — the same export `RUN_STYLE_NAMES` already is, so a tool that offers them reads the engine rather than keeping a copy.
+- **A document may mark a declaration `required`, and `plan` checks it against the targets you name.** `"required": { "uppercase": true }` at the report root says which declarations this document cannot do without; `plan(schema, funcs, { targets })` takes the `capabilities` descriptors of the targets it is meant for, and 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. An approximated declaration is not one. Every withdrawal was silent by design before this, so this is how an author says that one of them matters. Additive throughout: no target sees the marking, no render changes because of it, and passing no descriptors checks nothing. A name outside the set the support matrix answers for is a definition error, because a marking nothing can check would go quiet exactly when it was needed. `REQUIRABLE` exports that set.
+
+### Patch Changes
+
+- **The declarations now state every `format` modifier the engine settles.** `FormatDeclaration` and `ResolvedFormat` carry `negative` and `zero` beside `digits` and `form`, and `FORMAT_VOCABULARY` offers the two readings and their defaults — `negatives`, `zeroes`, `defaultNegative`, `defaultZero` — with `modifiers` naming every modifier a kind takes rather than one of them. The engine has always read and resolved those declarations; the types said otherwise, so a TypeScript consumer writing one was told it was an error, and a tool reading the vocabulary to offer them found only the count.
+- **An error quario replaces keeps the one it replaced, as `cause`.** A failure inside one of your own functions reaches you named where it happened — `detail[0].value [{{ total() }}]: ...` — which is a copy, rebuilt from the class and a prefixed message. The stack that says which line of your function threw used to go with the original. It now rides along: read `error.cause` for the throw as it happened, and the message for where quario was when it happened.
+
+  The viewer's and the editor's own property checks do the same. A `page` or `fonts` value either element refuses throws a `TypeError` naming the property, and that error now carries the layout's own account of the value behind it.
+
+- **An all-authored split whose slot widths sum under 100 warns, as a table's columns already did.** A split's slots carry the same percentage shares under the same arithmetic, so the plan now reports the trailing width they leave unused, on the split's `slots` path. The report still renders; the warning is advisory, like every other.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -193,6 +193,8 @@ cell the same way:
   group's.
 - `STYLE_NAMES` — the closed style vocabulary, in the spec's order, and
   `RUN_STYLE_NAMES` — the inline half of it, which is what a styled run may wear.
+- `isBoxName(name)` — whether a style name is part of the box, a padding or a border part. The
+  spec defines a row's box by this partition, and this function is its one home.
 
 ### `validate(schema, functions?)`
 
@@ -207,7 +209,7 @@ 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.
 
-### `quario().plan(schema, functions?)`
+### `quario().plan(schema, functions?, { targets }?)`
 
 The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns
 `{ report, problems, anchors, warnings }`: the compiled report (`null` while the document has
@@ -226,6 +228,21 @@ a cell whose `format` is not `"currency"`, and a table where the author sized ev
 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.
 
+**`targets` checks the document against where it is going.** A document may mark declarations it
+cannot do without — `"required": { "uppercase": true }` at its root — and hand `plan` the
+`capabilities` descriptors of the targets it is meant for. Each required declaration one of them
+withdraws, or leaves unread as the page bands are, becomes a problem of its own at
+`required.<name>`, which nulls the report as any other problem does. An approximated one does not:
+the target rendered the intent as closely as it can. Pass no descriptors and nothing is checked,
+which is what keeps the marking additive. It is never a render-time failure.
+
+```js
+import { capabilities as csv } from "@quario/csv";
+
+const { problems } = quario().plan(schema, undefined, { targets: [csv] });
+// required.uppercase: the csv target withdraws "uppercase"
+```
+
 ```js
 const { report, problems, anchors, warnings } = quario().plan(schema);
 for (const warning of warnings) console.warn(warning.message);

package/lib/band-height.js

@@ -16,7 +16,7 @@
  * lands in the documented key order beside every other problem.
  */
 
-import { isExpr, positivePts } from "./style.js";
+import { positivePts } from "./style.js";
 
 /**
  * A lead: authored flow spacing before an item that a target would actually
@@ -43,29 +43,20 @@ export let LEAD_REFUSED = "must be 0 after a height-declared header";
  */
 export let leadPath = (path) => path + ".style.spaceBefore";
 
-/**
- * An occupancy the document leaves to the data: a `visible` written as an
- * expression, or an image, whose bytes are expression-only and whose event is
- * absent when its `source` yields nothing (SCHEMA.md, "Event stream"). Neither
- * is a defect — they are how an author writes an optional item — but they mean
- * the traversal cannot say which item comes first, so it says nothing rather
- * than guessing (docs/adr/0052).
- *
- * @type {(def: any) => boolean}
- */
-let dataDecides = (def) => isExpr(def?.visible) || def?.type === "image";
-
 /**
  * The first item of a band the document settles as occupying, `undefined` when
  * only the render settles it, and null for a band settled to occupy nothing.
+ * Whether an item's occupancy is the data's to decide is `optional`'s answer,
+ * which the item compilers own: this file knows what a lead is and which node
+ * a fault names, not which item kinds can decline to render.
  *
- * @type {(list: any, path: string) => { def: any, path: string } | undefined | null}
+ * @type {(optional: (def: any) => boolean, list: any, path: string) => { def: any, path: string } | undefined | null}
  */
-let firstOccupying = (list, path) => {
+let firstOccupying = (optional, list, path) => {
   if (!Array.isArray(list)) return null;
   let i = list.findIndex((def) => def?.visible !== false);
   if (i < 0) return null;
-  return dataDecides(list[i]) ? undefined : { def: list[i], path: path + "[" + i + "]" };
+  return optional(list[i]) ? undefined : { def: list[i], path: path + "[" + i + "]" };
 };
 
 /**
@@ -84,11 +75,14 @@ let firstOccupying = (list, path) => {
  * a table, a row and a cell alike.
  *
  * @param {(path: string, message: string) => void} bad The traversal's collector.
+ * @param {(def: any) => boolean} optional Whether an item definition may
+ *   decline to occupy at render — the item compilers' verdict, so a new item
+ *   kind that can states it where it is compiled rather than here.
  * @returns {{ arm: (height: number | null) => void,
  *   instead: (list: any, path: string) => void,
  *   body: (list: any, path: string) => void }} The guard.
  */
-export let pinGuard = (bad) => {
+export let pinGuard = (bad, optional) => {
   let pinned = false;
   let settled = true;
   /** @type {(found: { def: any, path: string } | undefined | null) => void} */
@@ -101,11 +95,11 @@ export let pinGuard = (bad) => {
       settled = !pinned;
     },
     instead: (/** @type {any} */ list, /** @type {string} */ path) => {
-      if (pinned) refuse(firstOccupying(list, path));
+      if (pinned) refuse(firstOccupying(optional, list, path));
     },
     body: (/** @type {any} */ list, /** @type {string} */ path) => {
       if (settled) return;
-      let found = firstOccupying(list, path);
+      let found = firstOccupying(optional, list, path);
       // A band settled to occupy nothing is not the one under the box, so the
       // descent keeps looking; one only the render settles ends the search
       // without a verdict, because whether the band below is next is exactly

package/lib/format.js

@@ -16,7 +16,7 @@
  * rendered (docs/adr/0054, docs/adr/0056).
  */
 import { boundedMemo } from "./memo.js";
-import { currencyOf, formatOf } from "./style.js";
+import { ZERO_DASH, currencyOf, formatOf } from "./style.js";
 import { finiteDate, finiteNum, reviveDate } from "./stream.js";
 /** @type {(options: any) => string} */
 let localeOf = (options) => options?.locale || "en-US";
@@ -114,6 +114,34 @@ let asDate = (value, locale, decl, options) => {
 /** @type {Record<string, (value: any, locale: string, decl: any, options: any, style: any) => string | undefined>} */
 let KINDS = { number: asNumber, currency: asMoney, percent: asPercent, date: asDate };
 
+// The two presentation modifiers a number kind carries, applied around
+// whatever its own formatter produced. A `date` carries neither, and answers
+// `undefined` to both reads below.
+//
+// Parentheses are spelled here rather than taken from Intl's accounting sign:
+// the worksheet writes the same negative section into its number format, and
+// the two edges have to agree on one wording (docs/adr/0056, as amended).
+// Which is also why the number is formatted from its own magnitude — the sign
+// a locale would have written is exactly what the parentheses replace.
+/** @type {(value: any, decl: any) => any} */
+let magnitude = (value, decl) =>
+  decl.negative === "parens" && finiteNum(value) && value < 0 ? -value : value;
+// What each sign reads as, given the modifiers its kind carries. A table
+// rather than a chain, so the three cases are three entries and each one is
+// the whole answer for its sign.
+/** @type {Record<string, (text: string, decl: any) => string>} */
+let SIGNED = {
+  zero: (text, decl) => (decl.zero === "dash" ? ZERO_DASH : text),
+  negative: (text, decl) => (decl.negative === "parens" ? "(" + text + ")" : text),
+  positive: (text) => text,
+};
+// `value === 0` is true of a negative zero, which is a zero.
+/** @type {(value: number) => string} */
+let signOf = (value) => (value === 0 ? "zero" : value < 0 ? "negative" : "positive");
+/** @type {(value: any, text: string | undefined, decl: any) => string | undefined} */
+let presented = (value, text, decl) =>
+  text === undefined || !finiteNum(value) ? text : SIGNED[signOf(value)](text, decl);
+
 /**
  * The helper takes the whole resolved `style`, not just the declaration, so
  * the question "which declarations does presentation read?" is answered here
@@ -137,7 +165,8 @@ export function format(value, style, options) {
   let decl = formatOf(style, options);
   if (!decl) return;
   try {
-    return KINDS[decl.kind](value, localeOf(options), decl, options, style);
+    let text = KINDS[decl.kind](magnitude(value, decl), localeOf(options), decl, options, style);
+    return presented(value, text, decl);
   } catch {
     return;
   }

package/lib/index.d.ts

@@ -95,8 +95,9 @@ export interface StyleDeclarations extends BoxDeclarations {
   valign?: ExpressionValue<VAlign>;
   /**
    * How a number or date is presented: a kind, or an object naming one and
-   * carrying the single modifier that kind understands — `digits` for the
-   * three number kinds, `form` for `date`. Locale stays on the instance.
+   * carrying the modifiers that kind understands — `digits`, `negative` and
+   * `zero` for the three number kinds, `form` for `date`. Locale stays on the
+   * instance.
    */
   format?: ExpressionValue<FormatDeclaration>;
   /**
@@ -107,6 +108,14 @@ export interface StyleDeclarations extends BoxDeclarations {
    * than falling back to the instance's currency. Unread without the kind.
    */
   currency?: ExpressionValue<string>;
+  /**
+   * 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
+   * rather than passes on — a URL is admitted against the instance's `schemes`
+   * 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>;
   /** Blank space before this item, in points. */
   spaceBefore?: ExpressionValue<number>;
   /** Blank space after this item, in points. */
@@ -125,6 +134,28 @@ export interface SortKey {
  */
 export const RUN_STYLE_NAMES: readonly string[];
 
+/**
+ * The names a [report default](../../../SCHEMA.md#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.
+ */
+export const REPORT_STYLE_NAMES: readonly string[];
+
+/**
+ * What a cell reads as under `format`'s `zero: "dash"`. Stated once, because
+ * the XLSX target writes the same character into its sectioned number format
+ * and the two edges must agree.
+ */
+export const ZERO_DASH: string;
+
+/**
+ * The declarations a document may mark [`required`](../../../SCHEMA.md#validation),
+ * 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.
+ */
+export const REQUIRABLE: readonly string[];
+
 /**
  * The declarations a styled run accepts: the inline half of the vocabulary,
  * and nothing else. The box and flow spacing describe a block and `align`
@@ -145,6 +176,7 @@ export type RunStyleDeclarations = Pick<
   | "uppercase"
   | "format"
   | "currency"
+  | "href"
 >;
 
 /**
@@ -173,26 +205,42 @@ export type FormatKind = "number" | "currency" | "percent" | "date";
  * none is `"medium"`. */
 export type DateForm = "short" | "medium" | "long" | "full";
 
+/** How a negative amount reads. A number kind that names none is `"minus"`. */
+export type NegativeReading = "minus" | "parens";
+
+/** How a zero reads. A number kind that names none is `"number"`. */
+export type ZeroReading = "number" | "dash";
+
 /**
- * How an author writes `format`: the kind alone, or the kind carrying its one
- * modifier. `digits` is a whole number from 0 to 20 — the range both a
- * presenting target and a worksheet number format can honour — and it beats
+ * How an author writes `format`: the kind alone, or the kind carrying the
+ * modifiers it takes. `digits` is a whole number from 0 to 20 — the range both
+ * a presenting target and a worksheet number format can honour — and it beats
  * the count the kind would otherwise present, a currency's minor units
  * included. A modifier on a kind that does not take it is a definition error.
  */
 export type FormatDeclaration =
   | FormatKind
-  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | {
+      kind: "number" | "currency" | "percent";
+      digits?: number;
+      negative?: NegativeReading;
+      zero?: ZeroReading;
+    }
   | { kind: "date"; form?: DateForm };
 
 /**
  * What `format` resolves to on the event stream: never the shorthand, always
  * the kind with the answer it presents. A number kind carries `digits` unless
- * it has no count at all — a `currency` whose code cannot be read — and a
- * `date` always carries its `form`.
+ * it has no count at all — a `currency` whose code cannot be read — and both
+ * of its readings, and a `date` always carries its `form`.
  */
 export type ResolvedFormat =
-  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | {
+      kind: "number" | "currency" | "percent";
+      digits?: number;
+      negative: NegativeReading;
+      zero: ZeroReading;
+    }
   | { kind: "date"; form: DateForm };
 
 export interface Cell {
@@ -478,6 +526,14 @@ export interface QuarioOptions {
   currency?: string;
   /** Timezone for `format: "date"`. Defaults to `"UTC"`. */
   timeZone?: string;
+  /**
+   * The URL schemes an `href` may use, each lower-case and ending in a colon.
+   * Defaults to `https:` and `mailto:`. The allowlist is the host's, never the
+   * document's, and a value this cannot read throws at construction rather
+   * than falling back — an allowlist quietly replaced is a host believing it
+   * restricted something it had not.
+   */
+  schemes?: readonly string[];
 }
 
 /** The settled result of an instance's license key verification. */
@@ -696,6 +752,10 @@ export interface GroupStartEvent {
   depth: number;
   key: unknown;
   aggregates: Record<string, unknown>;
+  /** The instance's navigation name, resolved from the group's `label` and
+   *  joined to text. Absent where the group declares none, so a target with a
+   *  name it derives keeps deriving it. */
+  label?: string;
   /** 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`. */
@@ -704,6 +764,9 @@ export interface GroupStartEvent {
   reset?: "page";
   /** The declared page column count, present when the group declares one. */
   columns?: number;
+  /** The instance opens shut, present only when the group declares it: its
+   *  bands are shown and the content between them is not. */
+  collapsed?: true;
 }
 
 export interface GroupEndEvent {
@@ -801,6 +864,18 @@ export type WalkEvent = ReportEvent | SplitEvent;
  */
 export function splits(events: Iterable<ReportEvent>): Generator<WalkEvent, void>;
 
+/**
+ * Each [collapsed](../../../SCHEMA.md#group-definition) instance shut: its
+ * brackets and its own header and footer items survive, and everything
+ * between them is dropped, nested instances whole.
+ *
+ * For a target with no way to hide a row and keep it. One that has — the
+ * worksheet — reads the stream as it is. Aggregates are untouched either
+ * way. Read it over `splits(stream)`, so a split inside a header arrives
+ * folded and wearing the role this reads.
+ */
+export function collapse(events: Iterable<WalkEvent>): 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
@@ -897,6 +972,27 @@ export interface Warning {
  * complement of `names`, which excludes them. `problems` is fatal and
  * `warnings` is advisory, both in document order from the one descent.
  */
+/** A target's `capabilities` descriptor, as each published target exports it. */
+export interface TargetCapabilities {
+  readonly target: string;
+  readonly declarations: Readonly<Record<string, string>>;
+}
+
+/** What a caller asks `plan` to check beyond the document itself. */
+export interface PlanOptions {
+  /**
+   * The `capabilities` descriptors of the targets this document is meant for.
+   * Every declaration the document marks `required` that one of them
+   * withdraws or leaves unread becomes a problem of its own, which nulls the
+   * report exactly as any other problem does. Omit them and nothing is
+   * checked, which is what makes the marking additive.
+   *
+   * Descriptors rather than targets: the engine knows about no target, and
+   * what it reads here is the data a target ships about itself.
+   */
+  readonly targets?: readonly TargetCapabilities[];
+}
+
 export interface Plan {
   readonly report: CompiledReport | null;
   readonly problems: readonly Problem[];
@@ -917,7 +1013,7 @@ export interface Quario {
    * problems, advisory warnings, and per-node anchor sets — one descent per
    * edit for a host that validates and renders in a loop.
    */
-  plan(schema: unknown, functions?: FunctionRegistry): Plan;
+  plan(schema: unknown, functions?: FunctionRegistry, options?: PlanOptions): Plan;
 }
 
 /**
@@ -1069,6 +1165,14 @@ export function isReportBand(role: string | undefined): boolean;
  */
 export const STYLE_NAMES: readonly string[];
 
+/**
+ * Whether a style name belongs to the box: a padding or a border part. The
+ * partition is the spec's (a row's box is defined by it), and this is its one
+ * home. A target that strips the box off a style, or a tool that lists the box
+ * names, asks this rather than matching the prefixes itself.
+ */
+export function isBoxName(name: string): boolean;
+
 /**
  * The `format` vocabulary as data, for a tool that offers it rather than
  * checks it — a style rail's kind picker and its modifier control — so no
@@ -1077,9 +1181,14 @@ export const STYLE_NAMES: readonly string[];
 export const FORMAT_VOCABULARY: {
   readonly kinds: readonly FormatKind[];
   readonly forms: readonly DateForm[];
-  /** Which modifier each kind takes, so a surface offering the pair need not
-   * know that three kinds share `digits` and `date` does not. */
-  readonly modifiers: Readonly<Record<FormatKind, "digits" | "form">>;
+  readonly negatives: readonly NegativeReading[];
+  readonly zeroes: readonly ZeroReading[];
+  /** Which modifiers each kind takes, in the order a surface offers them, so
+   * one offering them need not know that three kinds share theirs and `date`
+   * does not. */
+  readonly modifiers: Readonly<Record<FormatKind, readonly string[]>>;
   readonly defaultForm: DateForm;
+  readonly defaultNegative: NegativeReading;
+  readonly defaultZero: ZeroReading;
   readonly maxDigits: number;
 };

package/lib/index.js

@@ -24,15 +24,29 @@ 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, splits, styledRuns, text, typed, walk } from "./stream.js";
+export {
+  breathe,
+  collapse,
+  display,
+  isReportBand,
+  splits,
+  styledRuns,
+  text,
+  typed,
+  walk,
+} from "./stream.js";
 export { format } from "./format.js";
 export {
   currencyOf,
   FORMAT_VOCABULARY,
   fractionDigits,
+  isBoxName,
+  REPORT_STYLE_NAMES,
+  ZERO_DASH,
   RUN_STYLE_NAMES,
   STYLE_NAMES,
 } from "./style.js";
+export { REQUIRABLE } from "./names.js";
 export { imageError, isDiagnostic } from "./locate.js";
 export { hostMeta, hostOptions } from "./host.js";
 
@@ -104,6 +118,63 @@ export function validate(schema, funcs) {
 /** @type {(entries: any[]) => readonly any[]} */
 let freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
 
+// The fates that lose the declaration, and how each one reads in a message.
+// `approximated` is not among them: the target rendered the intent as closely
+// as it can, which is what the author asked for (docs/adr/0008). An own-key
+// lookup, because a fate reaches this from a caller's own descriptor.
+/** @type {Record<string, (name: string) => string>} */
+let LOST = Object.assign(Object.create(null), {
+  withdrawn: (/** @type {string} */ name) => 'withdraws "' + name + '"',
+  unread: (/** @type {string} */ name) => 'leaves "' + name + '" unread',
+});
+
+// What a target makes of one name, from the descriptor it ships. An `unknown`
+// descriptor answers nothing rather than guessing: a caller may hold one from
+// a package older than the name.
+/** @type {(target: any, name: string) => string | undefined} */
+let fateOf = (target, name) => {
+  let declarations = target?.declarations;
+  return record(declarations) && Object.hasOwn(declarations, name) ? declarations[name] : undefined;
+};
+
+// A target's own name, for the message. A descriptor that names none is still
+// readable, so this never throws: `plan` reports on a document, and a caller's
+// malformed descriptor is not the document's fault.
+/** @type {(target: any) => string} */
+let calling = (target) => (typeof target?.target === "string" ? target.target : "a target");
+
+// Every required declaration a passed target loses, one problem each, in the
+// document's own order and then the caller's. Plan-time only: this never
+// reaches a render, which is what keeps whose-fault-is-a-render out of it
+// (docs/adr/0057).
+// The descriptors a caller named, or none — which is what makes the whole
+// marking additive: nothing is checked against a target nobody named.
+/** @type {readonly any[]} */
+let NO_TARGETS = Object.freeze([]);
+/** @type {(opts: any) => readonly any[]} */
+let named = (opts) => (Array.isArray(opts?.targets) ? opts.targets : NO_TARGETS);
+
+// What a caller asked to check beyond the document: the required declarations
+// its targets lose.
+/** @type {(planned: any, opts: any) => any[]} */
+let checked = (planned, opts) => unmet(planned.compiled?.required ?? NO_TARGETS, named(opts));
+
+// What one target loses of one name, or null where it keeps it.
+/** @type {(target: any, name: string) => any} */
+let loss = (target, name) => {
+  let fate = fateOf(target, name);
+  let said = fate === undefined ? undefined : LOST[fate];
+  if (!said) return null;
+  return {
+    path: "required." + name,
+    message: "required." + name + ": the " + calling(target) + " target " + said(name),
+  };
+};
+
+/** @type {(required: readonly string[], targets: readonly any[]) => any[]} */
+let unmet = (required, targets) =>
+  required.flatMap((name) => targets.map((target) => loss(target, name)).filter(Boolean));
+
 // The per-node anchor sets, as frozen host data (CONTEXT.md, "Freeze"): which
 // anchors and group handles each compiled source reads, keyed by schema path.
 /** @type {(anchors: Map<string, Set<string>>) => any} */
@@ -286,6 +357,21 @@ function assemble(planned, schema, marking, options) {
 
 /** @typedef {import("./license.js").LicenseInfo} LicenseInfo */
 
+// The `href` allowlist, checked once at construction rather than per cell.
+// It **throws** where every other host option is lenient: an allowlist is a
+// security control, and one the engine quietly replaced with its own default
+// would be a host believing it had restricted something it had not
+// (docs/adr/0085).
+/** @type {(schemes: unknown) => void} */
+let checkSchemes = (schemes) => {
+  if (schemes === undefined) return;
+  let listed =
+    Array.isArray(schemes) &&
+    schemes.every((scheme) => typeof scheme === "string" && /^[a-z][a-z0-9+.-]*:$/.test(scheme));
+  if (!listed)
+    throw Error("schemes: expected an array of lower-case URL schemes, each ending in a colon");
+};
+
 /**
  * Create a configured quario instance: the host-level options — license key,
  * query budgets. The key is verified once, here, and `license` settles with
@@ -295,14 +381,17 @@ function assemble(planned, schema, marking, options) {
  *
  * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
  *   license?: string, trust?: {publicKey?: string, release?: string},
- *   locale?: string, currency?: string, timeZone?: string}} [options]
+ *   locale?: string, currency?: string, timeZone?: string,
+ *   schemes?: readonly string[]}} [options]
  *   Host configuration. `trust` is internal, not API — see ./license.js.
- *   `locale` / `currency` / `timeZone` present `format` (docs/adr/0041).
+ *   `locale` / `currency` / `timeZone` present `format` (docs/adr/0041), and
+ *   `schemes` is the `href` allowlist (docs/adr/0085).
  * @returns {{license: Promise<LicenseInfo>,
  *   report: (schema: any, funcs?: Record<string, Function>) => any,
  *   plan: (schema: any, funcs?: Record<string, Function>) => any}} The instance.
  */
 export function quario(options) {
+  checkSchemes(options?.schemes);
   let { licensed, settled } = verify(options?.license, options?.trust);
   // The wording is the instance's, where the key is; the stream is what
   // states it, so nothing wraps a compiled stream to reach its first event.
@@ -337,12 +426,23 @@ export function quario(options) {
     // hands over the whole thing — the compiled report (null while the
     // document has problems), every problem structurally, and the per-node
     // anchor sets — so an editing host pays one traversal per edit, not two.
-    /** @type {(schema: any, funcs?: Record<string, Function>) => any} */
-    plan(schema, funcs) {
+    //
+    // `targets` is the opt-in half: hand it the `capabilities` descriptors of
+    // the targets this document is meant for, and every declaration it marks
+    // `required` that one of them withdraws or leaves unread becomes a
+    // problem of its own. Descriptors rather than targets, because the engine
+    // knows about no target (docs/adr/0014) — what it reads is the data a
+    // target ships about itself. Without them nothing checks, which is what
+    // makes the whole marking additive.
+    /** @type {(schema: any, funcs?: Record<string, Function>, opts?: any) => any} */
+    plan(schema, funcs, opts) {
       let planned = plan(schema, funcs, options);
+      // After the document's own, so a problem list still opens with what is
+      // wrong with the report rather than with where it is going.
+      let problems = planned.problems.concat(checked(planned, opts));
       return {
-        report: planned.problems.length ? null : wrap(assemble(planned, schema, marking, options)),
-        problems: freezeEntries(planned.problems),
+        report: problems.length ? null : wrap(assemble(planned, schema, marking, options)),
+        problems: freezeEntries(problems),
         anchors: freezeAnchors(planned.anchors),
         warnings: freezeEntries(planned.warnings),
       };

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-19"; // release-date
+let RELEASE = "2026-09-21"; // 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

@@ -83,15 +83,23 @@ export let imageError = (path, said, cause) => {
  * @type {(path: string, src: any, error: any, relocate?: false | ((e: any, o: { prefix: string, offset: number }) => any), offset?: number) => never}
  */
 export let locate = (path, src, error, relocate, offset = 0) => {
-  let prefix = (src === undefined ? path : path + " [" + String(src) + "]") + ": ";
+  // Every caller has the author source in hand -- a query, a template, an
+  // expression, an image's own `source` -- so the message always names it.
+  let prefix = path + " [" + String(src) + "]: ";
   let where = { [LOCATION]: { path, source: src } };
   if (relocate) throw Object.assign(relocate(error, { prefix, offset }), where);
   // A host throw keeps its own class — the located error is the same kind of
-  // failure, named where it happened — and gains no diagnostic metadata.
+  // failure, named where it happened — and gains no diagnostic metadata. The
+  // original rides along as `cause`: a replacement is a claim about what went
+  // wrong, and the only thing that can contradict it is the error it replaced
+  // (docs/adr/0084). Assigned rather than passed to the constructor, for the
+  // reason `imageError` states above — a foreign class need not accept an
+  // options bag.
   throw Object.assign(
     error instanceof Error
       ? new /** @type {any} */ (error.constructor)(prefix + error.message)
       : Error(prefix + String(error)),
     where,
+    { cause: error },
   );
 };