quario 0.5.0 → 0.6.0

package/lib/format.js

@@ -1,66 +1,174 @@
 /**
  * Present a cell's raw token as `number` / `currency` / `percent` / `date`.
- * Targets import this instead of each other: the stream keeps the kind on
- * `style` and the token raw, and HTML/PDF stringify at the edge. A kind on
- * the wrong type, or on null, contributes nothing — the caller falls back to
- * `display()`. Invalid locale or currency codes fail the same way.
+ * Targets import this instead of each other: the stream keeps the resolved
+ * declaration on `style` and the token raw, and HTML/PDF stringify at the
+ * edge. A kind on the wrong type, or on null, contributes nothing — the
+ * caller falls back to `display()`. Invalid locale or currency codes fail the
+ * same way. Under the `currency` kind a cell's own `style.currency` names the
+ * denomination and beats the instance's default code.
  *
  * Defaults (`en-US`, UTC) are pinned so a PDF without a host locale still
  * renders the same bytes on every machine (docs/adr/0041, docs/adr/0025).
+ *
+ * The kind, its digit count, and a date's form all come off the one resolved
+ * declaration `formatOf` answers — the same object the stream carries and the
+ * XLSX target builds its number formats from — so a cell shows the same
+ * digits wherever it is rendered (docs/adr/0054, docs/adr/0056). A kind that
+ * carries no count presents nothing here and the caller falls back to
+ * `display()`.
  */
+import { currencyOf, formatOf } from "./style.js";
 import { finiteDate, finiteNum, reviveDate } from "./stream.js";
 /** @type {(options: any) => string} */
 let localeOf = (options) => options?.locale || "en-US";
 /** @type {(options: any) => string} */
 let zoneOf = (options) => options?.timeZone || "UTC";
 
-/** @type {(value: any, locale: string) => string | undefined} */
-let asNumber = (value, locale) =>
-  finiteNum(value) ? new Intl.NumberFormat(locale).format(value) : undefined;
-/** @type {(value: any, locale: string) => string | undefined} */
-let asPercent = (value, locale) =>
-  finiteNum(value) ? new Intl.NumberFormat(locale, { style: "percent" }).format(value) : undefined;
-/** @type {(options: any) => string | null} */
-let currencyOf = (options) => {
-  let currency = options?.currency;
-  return typeof currency === "string" && currency ? currency : null;
+// Building an `Intl` formatter costs about 22 µs; using one costs 0.3 µs. A
+// report presents cell after cell from a handful of distinct formats, so
+// constructing per token spent 3.2 s on a hundred thousand presented cells
+// where 0.2 s does (a report of mixed currencies rendered to HTML), and the
+// formatters are memoised.
+//
+// **The key is everything the formatter is made from**, and it is values
+// rather than an object identity because no identity survives both paths: a
+// literal style block folds to one frozen declaration every cell shares, while
+// a block holding an `=` expression resolves a fresh one per cell (`plan.js`).
+// Keying on values hits in both. Get a piece of it wrong and one cell presents
+// under another's formatter -- a USD row reading as EUR -- which is the
+// failure `test/semantics.test.js` pins a pair for, one piece at a time. Each
+// pair must differ in **only** the piece it is there for: EUR against JPY
+// would prove nothing about the code, because their digit counts already
+// differ and that piece would separate them on its own.
+//
+// **The cap is the part to read**, because the key space is not the host's to
+// bound. A currency code reaches this from author data through
+// `currency: "=@.ccy"`, gated only to three uppercase letters, and `digits`
+// can be an `=` result too: 17,576 codes times 21 counts is 369,000 keys for a
+// single locale. Measured at 244 bytes retained per entry, that is about 90 MB
+// held for the life of the process on data nobody vetted.
+//
+// So the map is bounded, and past the bound it is emptied rather than grown.
+// A workload presenting more distinct formats than the cap pays what it paid
+// before any of this and never more, which is the one cost that needs no
+// argument -- and it can never hand back a formatter built for another cell,
+// because clearing forgets rather than reuses.
+//
+// 2048 leaves the margin a threshold like this wants on both sides: about
+// 500 KB at the cap, against a real report reaching a small multiple of the
+// ISO codes actually in circulation, which is under two hundred. Raising it
+// costs bytes and lowering it costs rebuilt formatters; neither is a
+// correctness knob.
+//
+// Memoising a fact that cannot change within an ICU version, like
+// `fractionDigits`' own minor-units map (docs/adr/0025).
+let CAP = 2048;
+/** @type {Map<string, any>} */
+let formatters = new Map();
+// A construction that throws -- an unreadable locale, zone, or currency code
+// -- caches nothing: it reaches `format()`'s own catch, and a later cell asks
+// again rather than finding nothing sitting in the map under a good key.
+// Missing on `undefined` rather than `has()`, which is what `precision.js`
+// needs because *it* caches an absent answer; a formatter is never one.
+/** @type {(key: string, make: () => any) => any} */
+let memo = (key, make) => {
+  let formatter = formatters.get(key);
+  if (formatter !== undefined) return formatter;
+  formatter = make();
+  if (formatters.size >= CAP) formatters.clear();
+  formatters.set(key, formatter);
+  return formatter;
 };
-/** @type {(value: any, locale: string, options: any) => string | undefined} */
-let asMoney = (value, locale, options) => {
-  let currency = currencyOf(options);
-  if (!finiteNum(value) || !currency) return;
-  return new Intl.NumberFormat(locale, { style: "currency", currency }).format(value);
+
+// The kind leads, so a number's key can never read as a date's; the currency
+// is empty for the two kinds that wear none.
+/** @type {(locale: string, decl: any, rest?: any) => string} */
+let numberKey = (locale, decl, rest) =>
+  decl.kind + "|" + locale + "|" + decl.digits + "|" + (rest?.currency || "");
+
+/** @type {(value: any, locale: string, decl: any, rest?: any) => string | undefined} */
+let asFixed = (value, locale, decl, rest) => {
+  if (!finiteNum(value) || decl.digits === undefined) return;
+  return memo(
+    numberKey(locale, decl, rest),
+    () =>
+      new Intl.NumberFormat(locale, {
+        ...rest,
+        minimumFractionDigits: decl.digits,
+        maximumFractionDigits: decl.digits,
+      }),
+  ).format(value);
+};
+
+/** @type {(value: any, locale: string, decl: any) => string | undefined} */
+let asNumber = (value, locale, decl) => asFixed(value, locale, decl);
+/** @type {(value: any, locale: string, decl: any) => string | undefined} */
+let asPercent = (value, locale, decl) =>
+  // `style: "percent"` multiplies by 100 and the digits count the *displayed*
+  // places, which is what Excel's `0.00%` already means too — so the count
+  // crosses to the sheet with no translation (docs/adr/0056).
+  asFixed(value, locale, decl, { style: "percent" });
+// The code the cell actually wears is what the digit count was asked about, not
+// the instance's: minor units are a property of the currency, so a row that
+// names JPY presents no decimals beside one naming EUR that presents two
+// (docs/adr/0041, docs/adr/0054).
+/** @type {(value: any, locale: string, decl: any, options: any, style: any) => string | undefined} */
+let asMoney = (value, locale, decl, options, style) => {
+  let currency = currencyOf(style, options);
+  return currency ? asFixed(value, locale, decl, { style: "currency", currency }) : undefined;
 };
 // A string in an accepted RFC 3339 form revives to the Date a host would have
 // injected, then presents like any other Date — including in the instance's
 // timezone, so a calendar date under a western zone presents as the day
 // before, exactly as an injected `new Date("2026-08-14")` does today. The two
 // spellings never disagree, which is the point (ADR 0041).
-/** @type {(value: any, locale: string, options: any) => string | undefined} */
-let asDate = (value, locale, options) => {
+//
+// The form is Intl's own `dateStyle`, and it is always present: a declaration
+// that named none resolved to `medium` (docs/adr/0056). This is the half that
+// does not converge — the worksheet approximates it (CONTEXT.md, "Form").
+// `date` leads for the same reason the number kinds do, so the two key shapes
+// live beside each other and "one piece at a time" is auditable in one place.
+/** @type {(locale: string, decl: any, zone: string) => string} */
+let dateKey = (locale, decl, zone) => "date|" + locale + "|" + decl.form + "|" + zone;
+
+/** @type {(value: any, locale: string, decl: any, options: any) => string | undefined} */
+let asDate = (value, locale, decl, options) => {
   let date = finiteDate(value) ? value : reviveDate(value);
-  return date
-    ? new Intl.DateTimeFormat(locale, { timeZone: zoneOf(options) }).format(date)
-    : undefined;
+  if (!date) return;
+  let zone = zoneOf(options);
+  return memo(
+    dateKey(locale, decl, zone),
+    () => new Intl.DateTimeFormat(locale, { timeZone: zone, dateStyle: decl.form }),
+  ).format(date);
 };
 
-/** @type {Record<string, (value: any, locale: string, options: any) => string | undefined>} */
+/** @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 helper takes the whole resolved `style`, not just the declaration, so
+ * the question "which declarations does presentation read?" is answered here
+ * once rather than once per target (docs/adr/0014).
+ *
  * @param {unknown} value The interpolation's pre-stringify token.
- * @param {unknown} kind A resolved `format` declaration.
+ * @param {{ format?: unknown, currency?: unknown } | null} [style] The cell's
+ *   resolved style block: its `format` declaration, and its own `currency`
+ *   code when it declares one.
  * @param {{ locale?: string, currency?: string, timeZone?: string } | null} [options]
- *   The instance's locale, currency code, and timezone.
+ *   The instance's locale, default currency code, and timezone.
  * @returns {string | undefined} The presented text, or nothing when this
  *   kind does not apply.
  */
-export function format(value, kind, options) {
-  if (typeof kind !== "string") return;
-  let present = KINDS[kind];
-  if (!present) return;
+export function format(value, style, options) {
+  // A style the stream resolved already carries its declaration whole; one a
+  // host built by hand may still hold the shorthand, so it is widened here
+  // rather than refused. No own-key guard on the lookup: `formatOf` answers a
+  // kind only from the closed vocabulary, which is exactly `KINDS`' own keys,
+  // so nothing an `=` expression resolved to can reach this table.
+  let decl = formatOf(style, options);
+  if (!decl) return;
   try {
-    return present(value, localeOf(options), options);
+    return KINDS[decl.kind](value, localeOf(options), decl, options, style);
   } catch {
     return;
   }

package/lib/index.d.ts

@@ -93,8 +93,20 @@ export interface StyleDeclarations extends BoxDeclarations {
    * and on a band image, whose boxes have no such slack.
    */
   valign?: ExpressionValue<VAlign>;
-  /** How a number or date is presented. Locale stays on the instance. */
-  format?: ExpressionValue<FormatKind>;
+  /**
+   * 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.
+   */
+  format?: ExpressionValue<FormatDeclaration>;
+  /**
+   * What this cell's money is denominated in, under `format: "currency"`:
+   * a three-letter ISO 4217 code, beating the instance's default. A literal
+   * that is not one is a definition error; an `=` result that is not one is
+   * 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>;
   /** Blank space before this item, in points. */
   spaceBefore?: ExpressionValue<number>;
   /** Blank space after this item, in points. */
@@ -113,6 +125,32 @@ export type Align = "left" | "center" | "right";
 export type VAlign = "top" | "middle" | "bottom";
 export type FormatKind = "number" | "currency" | "percent" | "date";
 
+/** The four named date forms, Intl's own `dateStyle`. A `date` that names
+ * none is `"medium"`. */
+export type DateForm = "short" | "medium" | "long" | "full";
+
+/**
+ * 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
+ * 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: "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`.
+ */
+export type ResolvedFormat =
+  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | { kind: "date"; form: DateForm };
+
 export interface Cell {
   value: CellValue;
   visible?: ExpressionValue<boolean>;
@@ -162,12 +200,32 @@ export interface ImageItem {
   style?: ImageStyleDeclarations;
 }
 
+/**
+ * What a text slot declares: the vocabulary less flow spacing, which is a
+ * band-item pad and does not apply inside a split.
+ */
+export type SlotStyleDeclarations = Omit<StyleDeclarations, "spaceBefore" | "spaceAfter">;
+
+/**
+ * What an image slot declares: an image item's names less flow spacing, plus
+ * `valign` — the one name an image accepts in a slot and nowhere else, because
+ * a slot's box is the split's height rather than the picture's own.
+ */
+export type SlotImageStyleDeclarations = Omit<
+  ImageStyleDeclarations,
+  "spaceBefore" | "spaceAfter"
+> &
+  Pick<StyleDeclarations, "valign">;
+
 /**
  * One slot of a split: an ordinary item, plus the width share that is a slot
  * property rather than an item one. A split may not stand in a slot —
  * placement inside placement is the coordinate system quario does not have.
  */
-export type SplitSlot = (TextItem | ImageItem) & {
+export type SplitSlot = (
+  | (Omit<TextItem, "style"> & { style?: SlotStyleDeclarations })
+  | (Omit<ImageItem, "style"> & { style?: SlotImageStyleDeclarations })
+) & {
   /** Slot width as a percentage of the content width (0 < width <= 100). */
   width?: number;
 };
@@ -232,6 +290,16 @@ export interface TotalRow {
   style?: StyleDeclarations;
 }
 
+/**
+ * The table's summary block: the rows, plus what belongs to the block rather
+ * than to any one of them. Its `style` is the layer below each row's — box
+ * under box, everything else under everything else — and exact `false` on its
+ * `visible` omits the block whole, its rows never evaluated.
+ */
+export interface TotalBlock extends TableRow {
+  rows: [TotalRow, ...TotalRow[]];
+}
+
 /**
  * The header row's own box — distinct from `TableHeader`, which is one
  * column's header cell. This is the box the row wears, replayed with the
@@ -245,7 +313,7 @@ export interface TableDetail {
   header?: TableHeaderBox;
   row?: TableRow;
   columns: [TableColumn, ...TableColumn[]];
-  total?: [TotalRow, ...TotalRow[]];
+  total?: TotalBlock;
 }
 
 export interface Group {
@@ -351,7 +419,10 @@ export interface QuarioOptions {
   license?: string;
   /** Locale for `format`. Defaults to `"en-US"` when a kind is presented. */
   locale?: string;
-  /** Currency code for `format: "currency"`. Absent, that kind contributes nothing. */
+  /**
+   * Default currency code for `format: "currency"`, overridden by a cell's own
+   * `style.currency`. Absent from both, that kind contributes nothing.
+   */
   currency?: string;
   /** Timezone for `format: "date"`. Defaults to `"UTC"`. */
   timeZone?: string;
@@ -393,7 +464,7 @@ export interface EventCell {
   /**
    * The definition's schema path, on cells that belong to one: a `row` cell
    * carries its column's (`detail.columns[i]`), a `total-row` cell its
-   * `detail.total[r].cells[i]` entry. Absent on page-band cells reached by closure.
+   * `detail.total.rows[r].cells[i]` entry. Absent on page-band cells reached by closure.
    */
   path?: string;
 }
@@ -406,14 +477,21 @@ export interface PageInfo {
   total: number;
 }
 
+/**
+ * What a page band closure hands back: the band's items as the walk would
+ * emit them, wearing the `page-header`/`page-footer` role — a text item, an
+ * image, or a split's bracket with one item per slot between it.
+ */
+export type PageBandEvent = ItemEvent | ImageEvent | SplitStartEvent | SplitEndEvent;
+
 /**
  * Per-render page band closures on `report-start` (present only when the
  * schema declares page bands). A paginated target calls them once per page;
- * each call returns resolved `page-header`/`page-footer` item events.
+ * each call returns that page's resolved band events.
  */
 export interface PageBandRenderers {
-  header?: (page: PageInfo) => (ItemEvent | ImageEvent)[];
-  footer?: (page: PageInfo) => (ItemEvent | ImageEvent)[];
+  header?: (page: PageInfo) => PageBandEvent[];
+  footer?: (page: PageInfo) => PageBandEvent[];
 }
 
 export interface ReportStartEvent {
@@ -523,10 +601,15 @@ export interface TableStartEvent {
   type: "table-start";
   /** Always `detail` — the table definition's schema path. */
   path: string;
-  /** One entry per column. `header` is absent when a neighbour's span covers it. */
-  columns: { header?: EventCell; path: string; width?: number }[];
-  /** The header-row box from `detail.header`, when declared. */
-  style?: Record<string, unknown>;
+  /**
+   * The header row: one cell per column a neighbour's span does not cover,
+   * so fewer cells than columns whenever one spans. Shaped like a `row`
+   * payload, `style` being what is left of `detail.header`'s block once its
+   * box has landed on these cells.
+   */
+  header: { cells: EventCell[]; style?: Record<string, unknown> };
+  /** The column geometry, one entry per column. */
+  columns: { width?: number }[];
 }
 
 export interface RowEvent {
@@ -706,6 +789,22 @@ export function validate(schema: unknown, functions?: FunctionRegistry): string[
  */
 export function isDiagnostic(e: unknown): e is QuarioDiagnostic;
 
+/**
+ * Mint an image failure named on the item that asked for the bytes — for a
+ * **render target**, which is where every image failure past the magic
+ * numbers happens: the engine vouches for those and no further.
+ *
+ * `path` is the image item's, from a stream event or a display-list op;
+ * `.source` is appended, that being the key an author would change. `said` is
+ * what failed in your own words, and a library's own message belongs after it
+ * rather than instead of it. The result is `cause`'s class, so an embedder's
+ * `RangeError` stays a `RangeError`, with `cause` set.
+ *
+ * Not a diagnostic: `isDiagnostic` does not answer for it, a decoder that
+ * refused a file being nobody's delegated engine.
+ */
+export function imageError(path: string | undefined, said: string, cause?: unknown): Error;
+
 /**
  * Join a token stream to display text: literals verbatim, values through
  * `display()`. Re-exported from sjabloon.
@@ -722,29 +821,62 @@ export function text(tokens: readonly Token[]): string;
 export function display(value: unknown): string;
 
 /**
- * Present a token for a resolved `format` kind. Returns nothing when the kind
- * does not apply, so the caller falls back to `display()`. Locale defaults to
- * `"en-US"`, dates to UTC.
+ * Which currency code a cell wears under `format: "currency"`: its own
+ * `style.currency` when it declares one — the gate's `null` included, which is
+ * why an unusable code presents nothing rather than the instance's currency —
+ * else the instance default. Exported for a target that needs the code itself
+ * rather than the presented text, as the XLSX one does.
+ */
+export function currencyOf(
+  style?: { currency?: unknown } | null,
+  options?: { currency?: string } | null,
+): string | null;
+
+/**
+ * Present a token for a cell's resolved `style`. Reads the `format` kind and,
+ * under `"currency"`, the cell's own `currency` code; returns nothing when the
+ * kind does not apply, so the caller falls back to `display()`. Locale
+ * defaults to `"en-US"`, dates to UTC.
  */
 export function format(
   value: unknown,
-  kind: unknown,
+  style?: { format?: unknown; currency?: unknown } | null,
   options?: { locale?: string; currency?: string; timeZone?: string } | null,
 ): string | undefined;
 
+/**
+ * How many fraction digits a cell presents. Takes the whole style, as
+ * `format()` and `currencyOf()` do. `number` and `percent` present a fixed
+ * count, `currency` its currency's minor units, and a declared `digits` beats
+ * either — so the digits converge wherever the cell is rendered.
+ *
+ * A resolved style carries the answer on `style.format.digits` and a target
+ * reads it there; this is for a host holding a style the stream has not
+ * resolved, and the shorthand is widened here first.
+ *
+ * Returns nothing when the cell presents no count: `date`, no `format`, an
+ * unknown kind, and a `currency` with no code or one Intl will not read. A
+ * caller that gets nothing presents some other way — `format()` falls back to
+ * `display()`, and a worksheet writes no number format.
+ */
+export function fractionDigits(
+  style?: { format?: unknown; currency?: unknown } | null,
+  options?: { currency?: string } | null,
+): number | undefined;
+
 /**
  * The typed-cell seam: exactly one value token holding a finite number, a
  * boolean, or a valid Date keeps its 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"`, a string in either accepted RFC 3339 form —
+ * Passing the cell's resolved `format` declaration opts into the seam's one
+ * coercion: under the `date` kind, a string in either accepted RFC 3339 form —
  * `YYYY-MM-DD`, or a timestamp naming its offset — revives to the Date it
  * names. Omitting the argument leaves the seam as it was.
  */
 export function typed(
   tokens: readonly Token[],
-  kind?: unknown,
+  decl?: ResolvedFormat | FormatKind,
 ): number | boolean | Date | undefined;
 
 /**
@@ -762,3 +894,18 @@ export function isReportBand(role: string | undefined): boolean;
  * keeping a copy.
  */
 export const STYLE_NAMES: readonly string[];
+
+/**
+ * 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
+ * surface keeps a copy that has to be told about a change.
+ */
+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 defaultForm: DateForm;
+  readonly maxDigits: number;
+};

package/lib/index.js

@@ -13,6 +13,7 @@
  * siblings beside it, one seam each. See SCHEMA.md for the document shape.
  */
 import { relocate as relocateQuery } from "padvinder";
+import { LEAD_REFUSED, isLead, leadPath } from "./band-height.js";
 import { MARKING, verify } from "./license.js";
 import { err, fault, locate } from "./locate.js";
 import { BLOCKED, NAME, record } from "./names.js";
@@ -25,8 +26,8 @@ import { opt } from "./stream.js";
 // imports them from the package, not from a file inside it.
 export { breathe, display, isReportBand, text, typed, walk } from "./stream.js";
 export { format } from "./format.js";
-export { STYLE_NAMES } from "./style.js";
-export { isDiagnostic } from "./locate.js";
+export { currencyOf, FORMAT_VOCABULARY, fractionDigits, STYLE_NAMES } from "./style.js";
+export { imageError, isDiagnostic } from "./locate.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */
 
@@ -134,16 +135,19 @@ function events(schema, funcs, options, marking) {
 /** @type {(event: any) => boolean} */
 let occupying = (event) =>
   event.type === "item" || event.type === "image" || event.type === "split-start";
-/** @type {(n: any) => boolean} */
-let nonzeroLead = (n) => Number.isFinite(n) && n !== 0;
-/** @type {(event: any) => string} */
-let eventPath = (event) => event.path || "header";
 /** @type {(event: any) => void} */
 let refuseLead = (event) => {
-  if (nonzeroLead(event.style?.spaceBefore))
-    fault(eventPath(event) + ".style.spaceBefore", "must be 0 after a height-declared header");
+  if (isLead(event.style?.spaceBefore)) fault(leadPath(event.path), LEAD_REFUSED);
 };
-/** @type {(events: Iterable<any>) => Generator<any>} */
+/**
+ * Refuse the lead the document could not settle. `plan()` has already refused
+ * every candidate the document itself decides (./band-height.js); what reaches
+ * here is the rest — a lead that is an expression, or an item whose occupancy
+ * only the data knows — so the first occupying event of the band under the
+ * pinned box is the one this sees, whichever band that turned out to be.
+ *
+ * @type {(events: Iterable<any>) => Generator<any>}
+ */
 function* guardPin(events) {
   let pending = true;
   for (let event of events) {

package/lib/license.js

@@ -11,7 +11,7 @@
 // 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-05"; // x-release-please-date
+let RELEASE = "2026-09-07"; // x-release-please-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

@@ -37,6 +37,38 @@ export let fault = (path, msg) => {
   throw Object.assign(Error(path + ": " + msg), { [LOCATION]: { path } });
 };
 
+/**
+ * An image failure a **target** raises, named on the item that asked for the
+ * bytes. The engine vouches for an image's magic numbers and no further
+ * (SCHEMA.md, "Image item"), so every failure past that point belongs to
+ * whichever target was sizing or embedding the file — and each of them was
+ * inventing its own wording, down to a corrupt PNG reaching a host as
+ * pdf-lib's bare "Invalid typed array length: 0" (quario-e0bz).
+ *
+ * Here rather than in a target because three of them raise it and no two of
+ * them may depend on each other; the engine is what they all already have.
+ * Minted rather than thrown, unlike `fault` beside it, so a caller can raise
+ * it from a `catch` or a rejection in whichever style its own code is.
+ *
+ * The shape is the one every render error has: the path prefixes the message
+ * and the failing class survives behind it. It carries no `LOCATION` and is no
+ * `isDiagnostic` diagnostic — the traversal never sees it, and a decoder that
+ * refused a file is not a delegated engine.
+ *
+ * @type {(path: string | undefined, said: string, cause?: unknown) => Error}
+ */
+export let imageError = (path, said, cause) => {
+  let error = TypeError((path ? path + ".source: " : "") + said, { cause });
+  // Wear the failing class rather than construct it. Keeping
+  // `e instanceof RangeError` true matters — a host may already be catching
+  // one — but the class is a library's and its constructor need not take
+  // `(message, options)` at all: one taking other arguments would mangle the
+  // message and swallow `cause`, turning a located failure back into the
+  // stray throw this exists to replace. Reparenting asks the class for
+  // nothing, so there is no call to check and nothing it can refuse.
+  if (cause instanceof Error) Object.setPrototypeOf(error, Object.getPrototypeOf(cause));
+  return error;
+};
 /**
  * Re-throw `error` located at `path`, with `src` — the offending author
  * source — in the message.