quario 0.1.0 → 0.2.0

package/lib/plan.js

@@ -31,21 +31,23 @@
 // Each engine's own predicate, not the union `locate.js` exports: every call
 // site knows which engine it just called, and asking that one is what stops a
 // sjabloon-shaped error being trusted where an xprsn error was expected.
-import { isDiagnostic as isQueryDiagnostic, query } from "padvinder";
-import { compile, isDiagnostic as isXprsnDiagnostic } from "xprsn";
-import { isDiagnostic as isTemplateDiagnostic, template } from "sjabloon";
-import { err, locate } from "./locate.js";
+import { isDiagnostic as isQueryDiagnostic, query, relocate as relocateQuery } from "padvinder";
+import {
+  compile,
+  isDiagnostic as isXprsnDiagnostic,
+  relocate as relocateXprsn,
+  signatures,
+} from "xprsn";
+import {
+  isDiagnostic as isTemplateDiagnostic,
+  relocate as relocateTemplate,
+  template,
+} from "sjabloon";
+import { LOCATION, fault, isDiagnostic, locate } from "./locate.js";
 import { ANCHORS, BLOCKED, NAME, RESERVED, record } from "./names.js";
 import { AGG, REDUCERS, RUN, aggregateValue, withRow } from "./scope.js";
 import { opt, sniff } from "./stream.js";
-import { checkImageStyle, checkStyle } from "./style.js";
-
-// Default traversal budget for the data query. Render input is untrusted, so
-// without a bound a deep document exhausts the native stack as an opaque
-// RangeError; with it, padvinder throws a typed PADVINDER_MAX_DEPTH diagnostic
-// long before that. Hosts override (or effectively disable) it per key through
-// `options.query`. 500 is ~4x inside the stack limit and far beyond report data.
-let QUERY = { maxDepth: 500 };
+import { checkImageStyle, checkReportStyle, checkStyle } from "./style.js";
 
 // Tolerance on the column-width sum. Widths are literal numbers an author may
 // write as thirds, so an exact comparison rejects 33.3 x 3 for a rounding error
@@ -67,19 +69,58 @@ let isExpr = (value) => typeof value === "string" && value[0] === "=";
 let collect = (from, into) => {
   for (let name of from) into.add(name);
 };
-/** @type {(from: Iterable<string>, bound: Set<string>, into: Set<string>) => void} */
-let collectFree = (from, bound, into) => {
-  for (let name of from) {
-    // oxlint-disable-next-line no-unused-expressions
-    bound.has(name) || into.add(name);
-  }
-};
 /** @type {(visible: any, scope: any) => any} */
 let hidden = (visible, scope) => visible && visible(scope) === false;
+
+// A text item's closed key set, and the same set inside a split, where the
+// slot's width share joins it.
+let TEXT_KEYS = ["type", "value", "visible", "style"];
+let TEXT_SLOT_KEYS = [...TEXT_KEYS, "width"];
+let IMAGE_KEYS = ["type", "source", "fit", "alt", "visible", "style"];
+let IMAGE_SLOT_KEYS = [...IMAGE_KEYS, "width"];
+
+// Which detail events carry the row's running values: the ones holding a cell.
+// A split's bracket holds none, so run rides the item and image events inside
+// it rather than the bracket around them.
+/** @type {(event: any) => boolean} */
+let carriesRun = (event) => event.type === "item" || event.type === "image";
 /** @type {(value: any, path: string, role: string, itemsOf: any) => any} */
 let maybeItems = (value, path, role, itemsOf) =>
   value != null ? itemsOf(value, path, role) : null;
 
+// The width-share rule, shared by a table's columns and a split's slots: the
+// two carry the same percentages under the same arithmetic, and one reader for
+// both is what keeps them from drifting into two rules wearing one name.
+/** @type {(sized: boolean, noun: string) => string} */
+let shareMsg = (sized, noun) =>
+  sized
+    ? "expected " + noun + " widths to total at most 100"
+    : "expected " +
+      noun +
+      " widths to total under 100, leaving room for the " +
+      noun +
+      "s without one";
+// The authored shares worth summing, or null when there is nothing to decide.
+// Nothing authored is nothing to check; a width out of range (a NaN, per the
+// width verdict) already carries its own problem, and one nobody can read
+// leaves it undecidable whether its part is one of those needing room.
+/** @type {(parts: { width?: any }[]) => number[] | null} */
+let sharesOf = (parts) => {
+  let shares = parts.map((part) => part.width).filter((width) => width != null);
+  return !shares.length || shares.some(Number.isNaN) ? null : shares;
+};
+// Authored shares must leave room for the parts without one. Widths are
+// literal, so the sum is known here; a tolerance keeps three at 33.3 from
+// summing to 100.00000000000001 and failing on IEEE 754 alone.
+/** @type {(bad: any, parts: { width?: any }[], path: string, noun: string) => void} */
+let checkShares = (bad, parts, path, noun) => {
+  let shares = sharesOf(parts);
+  if (!shares) return;
+  let total = shares.reduce((all, width) => all + width, 0);
+  let sized = shares.length === parts.length;
+  if (total > (sized ? 100 + WIDTH_EPS : 100 - WIDTH_EPS)) bad(path, shareMsg(sized, noun));
+};
+
 // One pass over a report's constants: it checks each value, copies it, and
 // freezes the copy. Copying is what keeps a consumer from reaching back into
 // the compiled schema through a nested object; freezing is what stops them
@@ -202,18 +243,42 @@ let planState = (schema, funcs) => {
   let BND = new Set(ANCHORS);
   bindHandles(schema, BND);
 
-  /** @type {string[]} */
+  // Structured problems: the path was a live value at every site that reports
+  // one, so it is kept as a field rather than recovered from the message. The
+  // message stays the whole located string — `validate()`'s view is
+  // `problems.map((p) => p.message)`, unchanged.
+  /** @type {{ path: string, source?: string, message: string, diagnostic?: any }[]} */
   let problems = [];
   // Kept so `events()` rethrows the engine's located error, not a bare one.
   /** @type {any} */
   let firstDiag = null;
+  // Where a caught error says it happened: `locate()` stamps that on the copy
+  // it throws, so nothing here parses a message back apart.
+  /** @type {(error: any) => { path: string, source?: any }} */
+  let where = (error) => (error && error[LOCATION]) || { path: "" };
+  // A caught error carries its location as data (locate.js), so the problem
+  // keeps the path and source structurally; the diagnostic rides along per
+  // problem — every problem keeps its offsets, not only the first.
+  /** @type {(msg: string, error?: any) => any} */
+  let located = (msg, error) => {
+    let at = where(error);
+    /** @type {any} */
+    let problem = { path: at.path, message: msg };
+    if (at.source !== undefined) problem.source = String(at.source);
+    if (isDiagnostic(error)) problem.diagnostic = error;
+    return problem;
+  };
   /** @type {(msg: string, error?: any) => void} */
   let add = (msg, error) => {
-    if (!problems.length && error && Object.hasOwn(error, "code")) firstDiag = error;
-    problems.push(msg);
+    // Identity, not shape: locate() copies an untrusted host throw with
+    // `new error.constructor(...)`, so a host class that stamps `code` on
+    // itself produces a copy shaped like a diagnostic. Only an error the
+    // engines authenticated is worth rethrowing as one (quario-lkz).
+    if (!problems.length && isDiagnostic(error)) firstDiag = error;
+    problems.push(located(msg, error));
   };
   /** @type {(path: string, msg: string) => void} */
-  let bad = (path, msg) => add(path + ": " + msg);
+  let bad = (path, msg) => problems.push({ path, message: path + ": " + msg });
   // Record a throwing compile step and stand in a stub, so the traversal reports
   // the whole definition rather than only its first fault.
   /** @type {<T>(fn: () => T, fallback: T) => T} */
@@ -231,6 +296,22 @@ let planState = (schema, funcs) => {
   /** @type {Set<string>} */
   let runNames = new Set();
 
+  // Which anchors each compiled source actually reads, keyed by its schema
+  // path. Retention, not computation: the engines report every root-name read
+  // in `.reads` — the unfiltered view `bound` keeps out of `.names` — and this
+  // keeps the anchor-and-handle subset a consumer placing a node needs.
+  /** @type {Map<string, Set<string>>} */
+  let anchors = new Map();
+  /** @type {(path: string, reads: { name: string }[]) => void} */
+  let anchorsOf = (path, reads) => {
+    for (let { name } of reads) {
+      if (!BND.has(name)) continue;
+      let set = anchors.get(path);
+      if (!set) anchors.set(path, (set = new Set()));
+      set.add(name);
+    }
+  };
+
   return {
     FNS,
     names,
@@ -238,6 +319,8 @@ let planState = (schema, funcs) => {
     BND,
     problems,
     runNames,
+    anchors,
+    anchorsOf,
     add,
     bad,
     attempt,
@@ -255,7 +338,7 @@ let compileProp = (source, path, FNS, BND) => {
   try {
     return compile(source.slice(1), FNS, { bound: BND });
   } catch (error) {
-    locate(path, source, error, 1, isXprsnDiagnostic(error));
+    locate(path, source, error, isXprsnDiagnostic(error) && relocateXprsn, 1);
   }
 };
 /** @type {(expression: any, path: string, source: any) => Eval} */
@@ -263,23 +346,23 @@ let runProp = (expression, path, source) => (scope) => {
   try {
     return expression(scope);
   } catch (error) {
-    locate(path, source, error, 1, expression.isDiagnostic(error));
+    locate(path, source, error, expression.isDiagnostic(error) && relocateXprsn, 1);
   }
 };
-/** @type {(src: string, path: string, source: any, FNS: any) => any} */
-let compileCell = (src, path, source, FNS) => {
+/** @type {(src: string, path: string, source: any, FNS: any, BND: Set<string>) => any} */
+let compileCell = (src, path, source, FNS, BND) => {
   try {
-    return template(src, FNS);
+    return template(src, FNS, { bound: BND });
   } catch (error) {
-    locate(path, source, error, 0, isTemplateDiagnostic(error));
+    locate(path, source, error, isTemplateDiagnostic(error) && relocateTemplate);
   }
 };
-/** @type {(tokens: any, path: string, source: any) => (scope: Scope, opts?: any) => any} */
-let runCell = (tokens, path, source) => (scope, opts) => {
+/** @type {(tokens: any, path: string, source: any) => (scope: Scope) => any} */
+let runCell = (tokens, path, source) => (scope) => {
   try {
-    return tokens(scope, opts);
+    return tokens.scoped(scope);
   } catch (error) {
-    locate(path, source, error, 0, isTemplateDiagnostic(error));
+    locate(path, source, error, tokens.isDiagnostic(error) && relocateTemplate);
   }
 };
 /** @type {(source: any) => string} */
@@ -293,16 +376,16 @@ let splitFold = (spec) => {
 /** @type {(colon: number, path: string) => void} */
 let checkCount = (colon, path) => {
   // oxlint-disable-next-line no-unused-expressions
-  colon < 0 || err(path + ": count does not take an expression");
+  colon < 0 || fault(path, "count does not take an expression");
 };
 /** @type {(src: string, fn: string, path: string) => void} */
 let checkExprFold = (src, fn, path) => {
   // oxlint-disable-next-line no-unused-expressions
-  (src.startsWith("=") && src.length > 1) || err(path + ': expected "' + fn + ':=<expression>"');
+  (src.startsWith("=") && src.length > 1) || fault(path, 'expected "' + fn + ':=<expression>"');
 };
 
 /** @param {State} state */
-let primitives = ({ FNS, BND, names, functions }) => {
+let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
   // A computed property: a literal, or an `=` xprsn expression. xprsn's
   // `bound` keeps engine-provided anchors/handles out of the reported `names`.
   /** @type {(spec: any, path: string) => Eval} */
@@ -311,23 +394,27 @@ let primitives = ({ FNS, BND, names, functions }) => {
     let expression = compileProp(source, path, FNS, BND);
     collect(expression.names, names);
     collect(expression.functions, functions);
+    anchorsOf(path, expression.reads);
     return runProp(expression, path, source);
   };
 
-  // A text cell: a sjabloon template, compiled with the token edition. Rendered
-  // with distinct `{ root, item }` anchors, so `@` is the current row and `$`
-  // is the report root. sjabloon already excludes its own loop vars / `$` / `@`;
-  // we drop quario's engine names (run, group handles) from the reported
-  // `names` too. A render yields the cell's public token stream: literal runs
-  // verbatim plus each interpolation's pre-stringify value. Templates have no
-  // raw form — a `{{{ }}}` tag is a located SJABLOON_RAW_TAG definition error —
-  // so escaping is entirely a render-target concern at the markup edge,
-  // with no exceptions to carry through the stream.
-  /** @type {(str: any, path: string) => (scope: Scope, opts?: any) => any} */
+  // A text cell: a sjabloon template, compiled with the token edition and
+  // rendered over quario's own scope chain, which already binds the anchors:
+  // `$` at the render base, `@` on the detail row, neither anywhere else — so
+  // a group or report band leaves `@` unbound and a stray `@.field` throws.
+  // sjabloon's `bound` excludes its loop vars / `$` / `@` and quario's engine
+  // names alike from the reported `names`. A render yields the cell's public
+  // token stream: literal runs verbatim plus each interpolation's
+  // pre-stringify value. Templates have no raw form — a `{{{ }}}` tag is a
+  // located SJABLOON_RAW_TAG definition error — so escaping is entirely a
+  // render-target concern at the markup edge, with no exceptions to carry
+  // through the stream.
+  /** @type {(str: any, path: string) => (scope: Scope) => any} */
   let cell = (source, path) => {
-    let tokens = compileCell(asText(source), path, source, FNS);
-    collectFree(tokens.names, BND, names);
+    let tokens = compileCell(asText(source), path, source, FNS, BND);
+    collect(tokens.names, names);
     collect(tokens.functions, functions);
+    anchorsOf(path, tokens.reads);
     return runCell(tokens, path, source);
   };
 
@@ -337,7 +424,7 @@ let primitives = ({ FNS, BND, names, functions }) => {
   let parseFold = (spec, path, allowed) => {
     let { fn, src, colon } = splitFold(spec);
     // oxlint-disable-next-line no-unused-expressions
-    allowed.has(fn) || err(path + ': unknown reducer "' + fn + '"');
+    allowed.has(fn) || fault(path, 'unknown reducer "' + fn + '"');
     if (fn === "count") checkCount(colon, path);
     else checkExprFold(src, fn, path);
     return { fn, per: src ? prop(src, path) : null };
@@ -371,10 +458,16 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
   };
   // Every schema object is a closed set, so typos and misplaced fields
   // (page.size, sort on a table detail) fail loud instead of doing nothing.
+  // One schema path from a parent's and a key. The document root's path is the
+  // empty string, so the dot is conditional -- `style.family`, never
+  // `.style.family`. Every reader that can be reached with the root joins
+  // through here rather than restating the rule.
+  /** @type {(path: string, key: string) => string} */
+  let pathTo = (path, key) => (path ? path + "." + key : key);
   /** @type {(value: any, allowed: string[], path: string) => void} */
   let keys = (value, allowed, path) => {
     for (let key of Object.keys(value))
-      if (!allowed.includes(key)) bad(path ? path + "." + key : key, 'unknown key "' + key + '"');
+      if (!allowed.includes(key)) bad(pathTo(path, key), 'unknown key "' + key + '"');
   };
   /** @type {(name: string, path: string, reserved?: Set<string> | null) => void} */
   let checkName = (name, path, reserved) => {
@@ -448,7 +541,7 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
     /** @type {[string, Eval][]} */
     let entries = [];
     for (let [name, value] of Object.entries(block)) {
-      let stylePath = path + ".style." + name;
+      let stylePath = path + "." + name;
       let problem = check(name, value);
       if (problem) bad(stylePath, problem);
       else entries.push([name, attempt(() => prop(value, stylePath), NIL)]);
@@ -482,8 +575,9 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
    */
   let stylesOf = (def, path, check = checkStyle) => {
     let block = def.style;
-    if (block == null || !obj(block, path + ".style")) return NIL;
-    return compileStyles(block, path, check);
+    let stylePath = pathTo(path, "style");
+    if (block == null || !obj(block, stylePath)) return NIL;
+    return compileStyles(block, stylePath, check);
   };
   // A cell value: one sjabloon template. Emphasis is the cell's own `style`;
   // markup in literal text is meaningful only to the HTML target.
@@ -617,19 +711,17 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
 let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, stylesOf }) => {
   // `tokens` plus its truthy `style`. A hidden cell keeps its slot with no
   // tokens so a column keeps its alignment; items pass `visible` null and drop
-  // themselves instead, having no slot to keep.
+  // themselves instead, having no slot to keep. The anchor story lives on
+  // `cell` in primitives: the scope chain itself carries `$` and `@`.
   /**
    * @type {(tpl: any, visible: Eval | null, styles: (scope: Scope) => any)
-   *   => (scope: Scope, item?: any) => any}
+   *   => (scope: Scope) => any}
    */
-  let cellShape = (tpl, visible, styles) => (scope, item) =>
-    opt(
-      { tokens: hidden(visible, scope) ? [] : tpl(scope, { root: scope["$"], item }) },
-      { style: styles(scope) },
-    );
+  let cellShape = (tpl, visible, styles) => (scope) =>
+    opt({ tokens: hidden(visible, scope) ? [] : tpl(scope) }, { style: styles(scope) });
 
   // A table cell: the shape of a total cell and of an object column header.
-  /** @type {(def: any, path: string, valuePath?: string) => (scope: Scope, item?: any) => any} */
+  /** @type {(def: any, path: string, valuePath?: string) => (scope: Scope) => any} */
   let cellOf = (def, path, valuePath = path + ".value") => {
     let tpl = cellValue(def.value, valuePath);
     let visible = visibleOf(def, path);
@@ -638,7 +730,7 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
 
   // A cell without a row, so `@` stays unbound. A bare string is shorthand for
   // `{ value }` and keeps its authored path, so problems locate where written.
-  /** @type {(def: any, path: string) => (scope: Scope, item?: any) => any} */
+  /** @type {(def: any, path: string) => (scope: Scope) => any} */
   let headerOf = (def, path) => {
     if (typeof def === "string") return cellShape(cellValue(def, path), null, NIL);
     if (!record(def)) {
@@ -668,10 +760,10 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     // A width is a percentage of the table width, resolved by every target.
     // The range verdict is owned here: an unreadable width comes back as NaN,
     // so the total check below reads the verdict instead of re-deciding it.
-    return { header, cell: cellShape(tpl, visible, styles), width: widthOf(def.width, path) };
+    return { header, cell: cellShape(tpl, visible, styles), width: widthOf(def.width, path), path };
   };
 
-  /** @type {(def: any, path: string) => ((scope: Scope, item?: any) => any) | null} */
+  /** @type {(def: any, path: string) => ((scope: Scope) => any) | null} */
   let totalOf = (def, path) => {
     if (!obj(def, path)) return null;
     keys(def, ["value", "visible", "style"], path);
@@ -679,29 +771,38 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
   };
 
   // A text item: a cell with no slot to keep, so a hidden one drops itself
-  // instead of keeping empty tokens the way a table cell does.
-  /** @type {(def: any, path: string, role: string) => (scope: Scope, item?: any) => any} */
-  let textOf = (def, path, role) => {
-    keys(def, ["type", "value", "visible", "style"], path);
-    // The fallback shape, so an unknown `type` is reported here -- after this
-    // node's key set, in the documented key order -- and then read as text, so
-    // the rest of its keys are checked rather than left behind the one problem.
-    if (def.type !== "text")
-      bad(path + ".type", def.type == null ? "required" : 'unknown item type "' + def.type + '"');
+  // instead of keeping empty tokens the way a table cell does. Inside a split
+  // it is the other way round -- a slot holds its place with empty tokens, so
+  // the line's geometry does not move with the data (SCHEMA.md, "Split item").
+  /** @type {(def: any, path: string, role: string, inSlot?: boolean) => (scope: Scope) => any} */
+  let textOf = (def, path, role, inSlot = false) => {
+    keys(def, inSlot ? TEXT_SLOT_KEYS : TEXT_KEYS, path);
+    checkTextType(def.type, path);
     let tpl = cellValue(def.value, path + ".value");
     let visible = visibleOf(def, path);
-    let shape = cellShape(tpl, null, stylesOf(def, path));
+    let shape = cellShape(tpl, inSlot ? visible : null, stylesOf(def, path));
     // The cell shape first, then the item's own fields, so a cell reads
     // the same wherever it appears in the stream.
-    return (scope, item) => {
-      if (hidden(visible, scope)) return null;
-      let event = shape(scope, item);
+    return (scope) => {
+      if (!inSlot && hidden(visible, scope)) return null;
+      let event = shape(scope);
       event.type = "item";
       event.role = role;
+      event.path = path;
       return event;
     };
   };
 
+  // The fallback shape's verdict on a `type` it does not name, reported after
+  // this node's key set and in the documented key order -- and then read as
+  // text, so the rest of its keys are checked rather than left behind the one
+  // problem.
+  /** @type {(type: any, path: string) => void} */
+  let checkTextType = (type, path) => {
+    if (type === "text") return;
+    bad(path + ".type", type == null ? "required" : 'unknown item type "' + type + '"');
+  };
+
   /** @type {(fit: any, path: string) => void} */
   let checkFit = (fit, path) => {
     if (fit == null || fit === "natural" || fit === "width") return;
@@ -709,10 +810,10 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
   };
   /** @type {(def: any, path: string) => any} */
   let altOf = (def, path) => (def.alt != null ? cellValue(def.alt, path + ".alt") : null);
-  /** @type {(alt: any, scope: Scope, item?: any) => any} */
-  let imageAlt = (alt, scope, item) => alt && alt(scope, { root: scope["$"], item });
-  /** @type {(fields: any, scope: Scope, item: any, bytes: any) => any} */
-  let imageEvent = (fields, scope, item, bytes) => {
+  /** @type {(alt: any, scope: Scope) => any} */
+  let imageAlt = (alt, scope) => alt && alt(scope);
+  /** @type {(fields: any, scope: Scope, bytes: any) => any} */
+  let imageEvent = (fields, scope, bytes) => {
     // The bytes stay bytes. Sniffing reads their magic numbers -- it never
     // decodes the image, and nothing here turns them into a string -- and
     // the answer rides on the event so no target sniffs a second time.
@@ -728,52 +829,125 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
         TypeError("expected a Uint8Array of PNG or JPEG bytes"),
       );
     return opt(
-      { type: "image", role: fields.role, bytes, format, fit: fields.fit },
-      { alt: imageAlt(fields.alt, scope, item), style: fields.styles(scope) },
+      { type: "image", role: fields.role, bytes, format, fit: fields.fit, path: fields.path },
+      { alt: imageAlt(fields.alt, scope), style: fields.styles(scope) },
     );
   };
-  /** @type {(fields: any) => (scope: Scope, item?: any) => any} */
-  let renderImage = (fields) => (scope, item) => {
+  /** @type {(fields: any) => (scope: Scope) => any} */
+  let renderImage = (fields) => (scope) => {
     if (hidden(fields.visible, scope)) return null;
     let bytes = fields.source(scope);
     // Nullish is the missing-data twin of `visible: false`: no event and no
     // error, so a report whose input sometimes lacks a logo needs no guard.
     if (bytes == null) return null;
-    return imageEvent(fields, scope, item, bytes);
+    return imageEvent(fields, scope, bytes);
   };
   // An image item: bytes an `=` expression yields, sized by `fit`, with an
   // optional textual stand-in. JSON has no way to write bytes, so `source` is
   // expression-only; the vocabulary an image accepts is `style.js`'s to narrow.
-  /** @type {(def: any, path: string, role: string) => (scope: Scope, item?: any) => any} */
-  let imageOf = (def, path, role) => {
-    keys(def, ["type", "source", "fit", "alt", "visible", "style"], path);
+  /** @type {(def: any, path: string, role: string, inSlot?: boolean) => (scope: Scope) => any} */
+  let imageOf = (def, path, role, inSlot = false) => {
+    keys(def, inSlot ? IMAGE_SLOT_KEYS : IMAGE_KEYS, path);
     let source = expression(def.source, path + ".source");
     checkFit(def.fit, path + ".fit");
-    return renderImage({
+    // Read in the documented key order, and each read once: `stylesOf` reports
+    // as it reads, so compiling it twice would report this node's style
+    // problems twice, and reading it early would report them out of order.
+    let alt = altOf(def, path);
+    let visible = visibleOf(def, path);
+    let styles = stylesOf(def, path, checkImageStyle);
+    let render = renderImage({
       source,
       fit: def.fit ?? "natural",
-      alt: altOf(def, path),
-      visible: visibleOf(def, path),
-      styles: stylesOf(def, path, checkImageStyle),
+      alt,
+      visible,
+      styles,
       path,
       sourceSpec: def.source,
       role,
     });
+    if (!inSlot) return render;
+    // A slot keeps its place whatever the data does: a hidden image, or a
+    // nullish source, leaves the same empty-token placeholder a hidden text
+    // slot leaves, so the widths either side of it do not move. `cellShape`
+    // with no template is that placeholder, so the two cannot drift.
+    let empty = cellShape(EMPTY, null, styles);
+    return (scope) => render(scope) ?? { ...empty(scope), type: "item", role };
   };
 
-  /** @type {(def: any, itemPath: string, role: string) => ((scope: Scope, item?: any) => any) | null} */
+  // One slot of a split: an ordinary item, plus the width share that is a slot
+  // property rather than an item one -- which is why `width` reaches an item's
+  // key set only here (docs/adr/0029).
+  /**
+   * @type {(def: any, path: string, role: string)
+   *   => { render: (scope: Scope) => any, width: any } | null}
+   */
+  let slotOf = (def, path, role) => {
+    if (!obj(def, path)) return null;
+    // Placement inside placement is the coordinate system quario does not
+    // have, so the nesting verdict is named rather than left to read as an
+    // unknown item type.
+    if (def.type === "split") {
+      bad(path + ".type", "a split cannot nest");
+      return null;
+    }
+    return {
+      render: (def.type === "image" ? imageOf : textOf)(def, path, role, true),
+      width: widthOf(def.width, path),
+    };
+  };
+
+  // A split: slots placed across the content width, bracketed in the stream so
+  // every slot crosses as the ordinary item or image event it already is.
+  /** @type {(def: any, path: string, role: string) => (scope: Scope) => any} */
+  let splitOf = (def, path, role) => {
+    keys(def, ["type", "slots", "visible", "style"], path);
+    let list = arr(def.slots, path + ".slots", true);
+    let defs = list || [];
+    // Two is the floor: a one-slot split is a text item wearing more syntax,
+    // and permitting it would be a second way to say one thing. Read off the
+    // array `arr` accepted, so a missing `slots` reports "required" once
+    // rather than that and this.
+    if (list && defs.length < 2) bad(path + ".slots", "expected at least two slots");
+    let slots = defs
+      .map((slot, i) => slotOf(slot, path + ".slots[" + i + "]", role))
+      .filter((slot) => slot != null);
+    checkShares(bad, slots, path + ".slots", "slot");
+    let visible = visibleOf(def, path);
+    let styles = stylesOf(def, path);
+    // Every width is a literal the traversal already resolved, so the geometry
+    // the bracket carries is the same array on every render -- built here
+    // rather than rebuilt per row in a detail band. Frozen because one array
+    // now reaches every render: a consumer must not be able to reach back
+    // through an event and change what a later render sees.
+    let geometry = Object.freeze(
+      slots.map((slot) => Object.freeze(opt({}, { width: slot.width }))),
+    );
+    return (scope) => {
+      if (hidden(visible, scope)) return null;
+      let out = [opt({ type: "split-start", role, slots: geometry }, { style: styles(scope) })];
+      for (let slot of slots) out.push(slot.render(scope));
+      out.push({ type: "split-end" });
+      return out;
+    };
+  };
+
+  /** @type {(def: any, itemPath: string, role: string) => ((scope: Scope) => any) | null} */
   let itemOf = (def, itemPath, role) => {
     if (!obj(def, itemPath)) return null;
     // `type` picks the item's shape; `textOf` owns the verdict on the ones
     // it does not name, having the closed key set that reports first.
+    if (def.type === "split") return splitOf(def, itemPath, role);
     return (def.type === "image" ? imageOf : textOf)(def, itemPath, role);
   };
-  /** @type {(list: ((scope: Scope, item?: any) => any)[]) => (scope: Scope, item?: any) => Generator<any>} */
+  /** @type {(list: ((scope: Scope) => any)[]) => (scope: Scope) => Generator<any>} */
   let yieldItems = (list) =>
-    function* (scope, item) {
+    function* (scope) {
       for (let render of list) {
-        let event = render(scope, item);
-        if (event) yield event;
+        let event = render(scope);
+        // A split renders to its whole bracket; every other item to one event.
+        if (Array.isArray(event)) yield* event;
+        else if (event) yield event;
       }
     };
 
@@ -781,10 +955,10 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
   // `q-<role>` class, which print CSS targets for styling and breaks.
   /**
    * @type {(value: any, path: string, role: string)
-   *   => (scope: Scope, item?: any) => Generator<any>}
+   *   => (scope: Scope) => Generator<any>}
    */
   let itemsOf = (value, path, role) => {
-    /** @type {((scope: Scope, item?: any) => any)[]} */
+    /** @type {((scope: Scope) => any)[]} */
     let list = [];
     for (let [i, def] of (arr(value, path) || []).entries()) {
       let render = itemOf(def, path + "[" + i + "]", role);
@@ -812,14 +986,15 @@ let bands = (
   { columnOf, itemsOf, totalOf },
 ) => {
   // Stacked items, one pass per row.
-  /** @type {(items: (scope: Scope, item?: any) => Generator<any>) => Band} */
+  /** @type {(items: (scope: Scope) => Generator<any>) => Band} */
   let itemsBand = (items) =>
     function* (rows, scope, runners) {
       for (let row of rows) {
         let scopeOfRow = runners.bind(scope, row);
         // Detail items carry the row's run values as data; group and report
         // band items never do (they have no current row).
-        for (let event of items(scopeOfRow, row)) yield opt(event, { run: scopeOfRow.run });
+        for (let event of items(scopeOfRow))
+          yield carriesRun(event) ? opt(event, { run: scopeOfRow.run }) : event;
       }
     };
 
@@ -833,30 +1008,6 @@ let bands = (
       rowStyles: stylesOf(value.row, "detail.row"),
     };
   };
-  /** @type {(sized: boolean) => string} */
-  let shareMsg = (sized) =>
-    sized
-      ? "expected column widths to total at most 100"
-      : "expected column widths to total under 100, leaving room for the columns without one";
-  /** @type {(columns: any[], shares: number[]) => void} */
-  let warnShares = (columns, shares) => {
-    let total = shares.reduce((all, width) => all + width, 0);
-    let sized = shares.length === columns.length;
-    if (total > (sized ? 100 + WIDTH_EPS : 100 - WIDTH_EPS)) bad("detail.columns", shareMsg(sized));
-  };
-  /** @type {(columns: any[]) => void} */
-  let checkShares = (columns) => {
-    // Authored shares must leave room for the columns without one. Widths are
-    // literal, so the sum is known here; a tolerance keeps three columns at
-    // 33.3 from summing to 100.00000000000001 and failing on IEEE 754 alone.
-    // Skipped outright when any authored width is out of range (a NaN, per
-    // columnOf's verdict): the document already carries that problem, and a
-    // width nobody can read leaves it undecidable whether its column is one
-    // of the ones needing room.
-    let shares = columns.map((column) => column.width).filter((width) => width != null);
-    if (!shares.length || shares.some(Number.isNaN)) return;
-    warnShares(columns, shares);
-  };
   /** @type {(value: any) => { defs: any[] | null, columns: any[] }} */
   let tableColumns = (value) => {
     let defs = arr(value.columns, "detail.columns", true);
@@ -864,7 +1015,7 @@ let bands = (
     let columns = (defs || [])
       .map((def, i) => columnOf(def, "detail.columns[" + i + "]"))
       .filter((column) => column != null);
-    checkShares(columns);
+    checkShares(bad, columns, "detail.columns", "column");
     return { defs, columns };
   };
   /** @type {(totals: any[] | null, defs: any[] | null) => void} */
@@ -874,7 +1025,12 @@ let bands = (
   };
   /** @type {(totals: any[]) => any[]} */
   let mapTotals = (totals) =>
-    totals.map((def, i) => totalOf(def, "detail.total[" + i + "]")).filter((cell) => cell != null);
+    totals
+      .map((def, i) => {
+        let cell = totalOf(def, "detail.total[" + i + "]");
+        return cell && { cell, path: "detail.total[" + i + "]" };
+      })
+      .filter((entry) => entry != null);
   /** @type {(value: any, defs: any[] | null) => any[] | null} */
   let tableTotals = (value, defs) => {
     let totals = arr(value.total, "detail.total");
@@ -890,7 +1046,12 @@ let bands = (
       let scopeOfRow = runners.bind(scope, row);
       if (!hidden(rowVisible, scopeOfRow))
         yield opt(
-          { type: "row", cells: columns.map((column) => column.cell(scopeOfRow, row)) },
+          {
+            type: "row",
+            cells: columns.map((column) =>
+              Object.assign(column.cell(scopeOfRow), { path: column.path }),
+            ),
+          },
           { style: rowStyles(scopeOfRow), run: scopeOfRow.run },
         );
     }
@@ -900,12 +1061,17 @@ let bands = (
     function* (rows, scope, runners) {
       yield {
         type: "table-start",
+        path: "detail",
         columns: columns.map((column) =>
-          opt({ header: column.header(scope) }, { width: column.width }),
+          opt({ header: column.header(scope), path: column.path }, { width: column.width }),
         ),
       };
       yield* tableRows(rows, scope, runners, columns, rowVisible, rowStyles);
-      if (total) yield { type: "total-row", cells: total.map((cell) => cell(scope)) };
+      if (total)
+        yield {
+          type: "total-row",
+          cells: total.map(({ cell, path }) => Object.assign(cell(scope), { path })),
+        };
       yield { type: "table-end" };
     };
   /** @type {(value: any) => Band} */
@@ -983,7 +1149,14 @@ let bands = (
         // A group band has no current row, so `@` stays unbound here.
         let { groupScope, aggregates, rows: ordered } = openInstance(ctx, key, groupRows, scope);
         yield opt(
-          { type: "group-start", name: ctx.name, depth: ctx.index, key, aggregates },
+          {
+            type: "group-start",
+            name: ctx.name,
+            depth: ctx.index,
+            key,
+            aggregates,
+            path: ctx.path,
+          },
           { break: ctx.pageBreak, reset: ctx.reset, columns: ctx.columns },
         );
         yield* ctx.header(groupScope);
@@ -1027,6 +1200,7 @@ let bands = (
       footer: itemsOf(def.footer, path + ".footer", "group-footer"),
       inner: bandOf(defs, index + 1, detail, columned || columns != null),
       name: def.name,
+      path,
       pageBreak: def.break,
       reset: def.reset,
       columns,
@@ -1053,9 +1227,12 @@ let bands = (
 /** @type {(source: string, options: any) => any} */
 let compileQuery = (source, options) => {
   try {
-    return query(source, undefined, { ...QUERY, ...(options && options.query) });
+    // padvinder itself defaults maxDepth to 500 (safety by construction since
+    // 0.6.0), so untrusted deep documents throw typed with no quario-side
+    // budget; hosts override per key — Infinity opts a budget out.
+    return query(source, undefined, options && options.query);
   } catch (error) {
-    locate("data", source, error, 0, isQueryDiagnostic(error));
+    locate("data", source, error, isQueryDiagnostic(error) && relocateQuery);
   }
 };
 /** @type {(schema: any, obj: any, named: any, bad: any) => any} */
@@ -1102,7 +1279,7 @@ let pageBands = (schema, obj, keys, itemsOf) => {
  */
 let traverse = (
   { add, bad, attempt, runNames },
-  { arr, obj, keys, named, expression, columnsOf, takeOf, foldsOf, sortOf },
+  { arr, obj, keys, named, expression, columnsOf, takeOf, foldsOf, sortOf, stylesOf },
   { itemsOf },
   { bandOf },
   schema,
@@ -1122,6 +1299,7 @@ let traverse = (
       "take",
       "aggregates",
       "run",
+      "style",
       "header",
       "empty",
       "columns",
@@ -1142,6 +1320,12 @@ let traverse = (
   let take = takeOf(schema.take, "take");
   let aggs = foldsOf(schema.aggregates, "aggregates", AGG, new Set(["params", "input"]));
   let running = foldsOf(schema.run, "run", RUN, null, runNames);
+  // The report default: one style block for the whole document, narrowed to
+  // the declarations a typeface is made of. It resolves once per render in
+  // report scope rather than per node, which is why it crosses the seam as a
+  // `report-start` field instead of being merged into every item's style --
+  // nothing here allocates per cell (docs/adr/0033).
+  let style = stylesOf(schema, "", checkReportStyle);
   let header = itemsOf(schema.header, "header", "report-header");
   // Null when undeclared, so the render decides on the compiled band rather
   // than reading `schema.empty` a second time from outside the traversal.
@@ -1160,6 +1344,7 @@ let traverse = (
     take,
     aggs,
     running,
+    style,
     header,
     empty,
     columns,
@@ -1189,8 +1374,15 @@ export let plan = (schema, funcs, options) => {
   return {
     compiled: traverse(state, read, node, band, schema, options),
     problems: state.problems,
+    anchors: state.anchors,
     names: state.names,
-    functions: state.functions,
+    // Registry metadata comes from xprsn's one signature convention, described
+    // over just the called subset — every called name resolved from the
+    // registry at compile time, and the rebuilt object keeps the flat name
+    // set's call-first-seen order.
+    functions: signatures(
+      Object.fromEntries(Array.from(state.functions, (name) => [name, state.FNS[name]])),
+    ),
     diagnostic: state.diagnostic,
   };
 };