sjabloon 0.9.0 → 0.11.0

package/README.md

@@ -67,7 +67,7 @@ Every edition exports `template`, `render`, `isDiagnostic`, and `relocate`. They
 
 ## API
 
-### `template(str, functions?)`
+### `template(str, functions?, options?)`
 
 Compiles the template and returns a renderer. What it renders to depends on the edition you imported from (see [Editions](#editions)); everything else on this page is identical across all three. Malformed tags, unclosed blocks, and invalid expressions throw a `SyntaxError` at compile time.
 
@@ -89,13 +89,42 @@ tpl.names; // => ['title', 'items']
 tpl.functions; // => ['fmt']
 ```
 
+`options.bound` lists names your engine already has in scope — a loop variable, a handle, a `page` anchor. They are excluded from `names` and still resolve normally at render time, the same contract as xprsn's own `bound`:
+
+```js
+template("{{ run.total }} of {{ count }}", undefined, { bound: ["run"] }).names; // => ['count']
+```
+
+The renderer also carries `reads`: every root-name read with its span in the template source, in source order. Duplicates, anchors, loop variables and bound names are all kept — `names` is the free, deduplicated view. This is what an editor squiggles, hovers, and jumps from:
+
+```js
+template("{{ title }}: {{ total }}").reads;
+// => [{ name: 'title', start: 3, end: 8 }, { name: 'total', start: 16, end: 21 }]
+```
+
+The renderer also carries its own `isDiagnostic(error)`: `true` only for runtime diagnostics thrown through this renderer, where the module-wide [`isDiagnostic`](#diagnostics) answers for every template. An embedder holding many compiled templates asks the one that just rendered, so a diagnostic that leaked from an unrelated template is not mistaken for this cell's.
+
+### `renderer.scoped(values)`
+
+The trusted-scope render, for an embedder whose scope chain already binds the anchors. The default call wraps `values` in a fresh scope and seeds `$` and `@` into it; `scoped` skips the wrapper: `$` and `@` resolve from `values` itself, and a chain that omits `@` leaves it unbound so `@.x` throws where there is no current item. `{{#each}}` still re-points `@` inside its body, and nothing is ever written to your objects. Rendering one template per cell per row over scopes you already build, this is the path with zero per-call allocations beyond the output.
+
+```js
+const row = Object.create(base); // base binds $ once per render
+row["@"] = item;
+tpl.scoped(row);
+```
+
 ### `render(str, values?, functions?)`
 
 Shorthand for `template(str, functions)(values)`, returning whatever its edition renders.
 
 ### `text(tokens)` (root entry only)
 
-Joins a token stream the way `sjabloon/text` would have rendered it: literals verbatim, values as `String(value ?? '')`. `text(template(str)(values))` and `sjabloon/text`'s `template(str)(values)` are equal for every template and every set of values. The test suite and the fuzzer both check that.
+Joins a token stream the way `sjabloon/text` would have rendered it: literals verbatim, values through `display()`. `text(template(str)(values))` and `sjabloon/text`'s `template(str)(values)` are equal for every template and every set of values. The test suite and the fuzzer both check that.
+
+### `display(value)` (root entry only)
+
+The scalar display rule every edition and `text()` share, exported for embedders that stringify token values themselves. A valid `Date` renders as ISO 8601 UTC (`toISOString()`) — the same bytes on every machine, where `String(date)` would bake in the host's timezone and locale. An invalid `Date` keeps its deterministic `'Invalid Date'` form, nullish displays empty, and everything else is `String(value)`.
 
 ```js
 import { template, text } from "sjabloon";

package/lib/core.js

@@ -5,8 +5,8 @@
  *
  * This is the shared core: the lexer, parser and diagnostics, with output left
  * to the profile each entry passes to `make()`. Exactly one copy of this module
- * backs every entry, so the WeakSet below authenticates diagnostics across all
- * of them.
+ * backs every entry, so the diagnostics store below authenticates diagnostics
+ * across all of them.
  */
 import { compile, isDiagnostic as isXprsnDiagnostic, relocate as relocateXprsn } from "xprsn";
 
@@ -30,10 +30,14 @@ import { compile, isDiagnostic as isXprsnDiagnostic, relocate as relocateXprsn }
  */
 
 const BLOCKED = /^(?:__proto__|constructor|prototype)$/;
-/** @type {WeakSet<any>} */
-const DIAGNOSTICS = new WeakSet();
-const mark = DIAGNOSTICS.add.bind(DIAGNOSTICS);
+// Error -> the `names` set of the compile that threw it. The map's keys are
+// what authenticates a diagnostic module-wide; the value is the per-template
+// origin each renderer's own `isDiagnostic` compares against.
+/** @type {WeakMap<any, any>} */
+const DIAGNOSTICS = new WeakMap();
+const mark = DIAGNOSTICS.set.bind(DIAGNOSTICS);
 const owns = DIAGNOSTICS.has.bind(DIAGNOSTICS);
+const origin = DIAGNOSTICS.get.bind(DIAGNOSTICS);
 
 /**
  * Check whether an error was produced or translated by sjabloon.
@@ -65,8 +69,9 @@ const kindOf = (p) => (p === SYNTAX ? SyntaxError : Error);
  * Copy a diagnostic into an embedder's coordinates.
  *
  * Relocation lives here, beside the authentication it has to satisfy: the copy
- * is registered in the same WeakSet as the original, so it passes
- * `isDiagnostic`. The original is never mutated, and every own field comes
+ * is registered in the same store as the original, under the original's origin,
+ * so it passes `isDiagnostic` and the owning renderer's own `isDiagnostic`
+ * alike. The original is never mutated, and every own field comes
  * across by descriptor — the frozen `blocks` context stays frozen and
  * non-writable — so a field added here is never a field an embedder forgets.
  *
@@ -86,7 +91,7 @@ export const relocate = (diag, { prefix = "", offset = 0 } = {}) => {
   // and attach would redefine a non-configurable property.
   if (isXprsnDiagnostic(diag)) {
     const moved = relocateXprsn(diag, { prefix, offset });
-    return (mark(moved), /** @type {SjabloonDiagnostic} */ (moved));
+    return (mark(moved, origin(diag)), /** @type {SjabloonDiagnostic} */ (moved));
   }
   let d = /** @type {any} */ (diag),
     props = DESCS(d),
@@ -98,7 +103,7 @@ export const relocate = (diag, { prefix = "", offset = 0 } = {}) => {
     props.end.value += offset;
   }
   DEFINE(copy, props);
-  return (mark(copy), /** @type {SjabloonDiagnostic} */ (copy));
+  return (mark(copy, origin(d)), /** @type {SjabloonDiagnostic} */ (copy));
 };
 
 // Linear scan into text/tag/raw tokens. Dashes hug braces (`{{- x -}}` trims;
@@ -127,6 +132,8 @@ let last;
 let bound;
 /** @type {Set<string>} */
 let names;
+/** @type {{ name: string, start: number, end: number }[]} */
+let reads;
 /** @type {Set<string>} */
 let functions;
 /** @type {string} */
@@ -219,11 +226,12 @@ let opener = (type, t) => {
  * @template {object} E
  * @param {E} e
  * @param {any} context
+ * @param {any} own The owning compile's `names` set, this diagnostic's origin.
  * @returns {E}
  */
-let attach = (e, context) => {
+let attach = (e, context, own) => {
   Object.defineProperty(e, "blocks", { value: context, enumerable: true });
-  mark(e);
+  mark(e, own);
   return e;
 };
 /**
@@ -250,21 +258,22 @@ const fault = (
   e.code = code;
   e.start = start;
   e.end = end;
-  throw attach(e, snap());
+  throw attach(e, snap(), names);
 };
 /**
  * Re-locate a diagnostic thrown by a nested compile or render into this
  * template's coordinates, then rethrow it as ours. Always throws.
  *
- * `owns` is a plain predicate rather than a type guard: `e` is retyped here,
+ * `guard` is a plain predicate rather than a type guard: `e` is retyped here,
  * not narrowed. `const` with an explicit `never` type is what lets callers
  * treat the catch block as terminal.
  *
- * @type {(e: any, start: number, context: any, owns?: (e: unknown) => boolean) => never}
+ * @type {(e: any, start: number, context: any, own: any,
+ *   guard?: (e: unknown) => boolean) => never}
  */
-const translated = (e, start, context, owns = isXprsnDiagnostic) => {
-  if (!owns(e)) throw e;
-  throw attach(relocateXprsn(e, { offset: start }), context);
+const translated = (e, start, context, own, guard = isXprsnDiagnostic) => {
+  if (!guard(e)) throw e;
+  throw attach(relocateXprsn(e, { offset: start }), context, own);
 };
 /**
  * @param {Tok} t
@@ -295,6 +304,9 @@ let run = (nodes, scope, acc) => {
  * @returns {(v: any) => any}
  */
 let compileExpr = (expr, start, context) => {
+  // The compiling template's origin, captured now: the render-time catch below
+  // runs long after the module-level `names` has moved on to other compiles.
+  const own = names;
   /** @type {ReturnType<typeof compile>} */
   let e;
   try {
@@ -305,21 +317,24 @@ let compileExpr = (expr, start, context) => {
     // than a real one — narrowing `SjabloonFunctions` would change the API.
     e = compile(expr, /** @type {any} */ (fns));
   } catch (x) {
-    translated(x, start, context);
+    translated(x, start, context, own);
   }
   e.names.forEach((n) => {
     // oxlint-disable-next-line no-unused-expressions
     bound.includes(n) || names.add(n);
   });
+  // Every read, shifted into template coordinates — bound names and loop
+  // variables included; `names` above stays the free, deduplicated view.
+  for (const r of e.reads) reads.push({ name: r.name, start: start + r.start, end: start + r.end });
   for (const fn of e.functions) functions.add(fn);
   return (v) => {
     try {
       return e(v);
     } catch (x) {
       // Read off the compiled expression to pass along, never called through
-      // `e` — xprsn's `isDiagnostic` is a closure over a WeakSet, not a method.
+      // `e` — xprsn's `isDiagnostic` is a closure over its store, not a method.
       // oxlint-disable-next-line typescript/unbound-method
-      translated(x, start, context, e.isDiagnostic);
+      translated(x, start, context, own, e.isDiagnostic);
     }
   };
 };
@@ -530,17 +545,42 @@ export const litNode = (text) => (scope, acc) => {
   acc.text += text;
 };
 
+/**
+ * Display text for one interpolated value — the scalar rule every edition and
+ * the root `text()` join share. A valid `Date` renders as ISO 8601 UTC
+ * (`toISOString()`), the same on every machine, where `String(date)` would
+ * bake in the host's timezone and locale; an invalid `Date` keeps its
+ * deterministic `"Invalid Date"` form. Nullish displays empty; everything
+ * else is `String(value)`.
+ *
+ * @param {unknown} value One rendered value.
+ * @returns {string} The display text.
+ */
+export const display = (value) =>
+  value instanceof Date && Number.isFinite(value.getTime())
+    ? value.toISOString()
+    : // Stringifying an arbitrary value is this rule's documented contract, so
+      // `no-base-to-string` is describing the feature rather than a mistake.
+      // oxlint-disable-next-line typescript/no-base-to-string
+      String(value ?? "");
+
 /**
  * Bind the parser to an output profile. Each edition calls this once at module
  * load and gets back its own `template` and `render`; the parser itself stays
- * module-level and shared, so there is exactly one diagnostics WeakSet.
+ * module-level and shared, so there is exactly one diagnostics store.
  *
- * `template(str, funcs?)` compiles a template once, to render it many times.
+ * `template(str, funcs?, opts?)` compiles a template once, to render it many
+ * times.
  *
  * The returned renderer exposes `names`: the variables the template reads
  * from your values, deduplicated. Loop variables the template introduces are
- * not included. It also exposes `functions`: the registry functions the
- * template calls, deduplicated.
+ * not included, and neither is anything in `opts.bound` — names the embedder
+ * already has in scope (still resolved normally at render time, exactly like
+ * xprsn's own `bound`). It also exposes `reads`: every root-name read with its
+ * span in the template source, in source order — duplicates, anchors, loop
+ * variables and bound names kept, so `names` is its free, deduplicated view.
+ * And `functions`: the registry functions the template calls, deduplicated. `isDiagnostic(error)` recognizes runtime
+ * diagnostics thrown through this renderer alone.
  *
  * Two anchors are always in scope: `$` is the root values, and `@` is the
  * current `#each` item (the root outside any loop). They let a nested loop
@@ -552,6 +592,12 @@ export const litNode = (text) => (scope, acc) => {
  * `root` and `@` becomes `item` (two distinct objects). Omit `item` to leave
  * `@` unbound, so reading `@.x` throws through xprsn's guard.
  *
+ * An embedder whose scope chain already binds the anchors renders through
+ * `scoped(values)` instead: no wrapper scope is created, `$` and `@` resolve
+ * from `values` itself, and a chain that omits `@` leaves it unbound the same
+ * way. That is the zero-allocation seam for a host rendering one template per
+ * cell per row over scopes it already builds.
+ *
  * Render order is push order into a single accumulator: loop bodies append once
  * per iteration, untaken branches append nothing, and block expressions (`#if`
  * conditions, `#each` collections) never append at all. The token edition
@@ -575,7 +621,8 @@ export const litNode = (text) => (scope, acc) => {
  *   take: (acc: A) => T,
  * ]} profile The output profile, as above.
  * @returns {{
- *   template: (str: string, funcs?: SjabloonFunctions) => SjabloonRenderer<T>,
+ *   template: (str: string, funcs?: SjabloonFunctions,
+ *     opts?: { bound?: Iterable<string> }) => SjabloonRenderer<T>,
  *   render: (str: string, values?: SjabloonValues, funcs?: SjabloonFunctions) => T,
  * }} That edition's API.
  * @throws {SyntaxError} `template` throws on malformed tags, unclosed blocks,
@@ -585,16 +632,22 @@ export let make = ([lit, val, raw, seed, take]) => {
   /**
    * @param {string} str
    * @param {SjabloonFunctions} [funcs]
+   * @param {{ bound?: Iterable<string> }} [opts]
    * @returns {SjabloonRenderer<T>}
    */
-  function template(str, funcs) {
+  function template(str, funcs, opts) {
     // oxlint-disable-next-line no-unused-expressions
     ((LIT = lit), (VAL = val), (RAW = raw));
     fns = funcs;
     // `$` (root) and `@` (current item) are engine-bound anchors, always in
-    // scope, so they never count as caller-supplied `names`.
+    // scope, so they never count as caller-supplied `names` — and neither does
+    // anything the embedder declares bound. A loop, not a spread: the
+    // bundler's transpile turns an iterable spread into a concat that would
+    // wrap a Set instead of unpacking it.
     bound = ["$", "@"];
+    if (opts && opts.bound) for (const name of opts.bound) bound.push(name);
     names = new Set();
+    reads = [];
     functions = new Set();
     source = String(str);
     blocks = [];
@@ -604,28 +657,41 @@ export let make = ([lit, val, raw, seed, take]) => {
     // Deeply nested blocks fail as SJABLOON_TOO_DEEP at DEPTH via opener(),
     // including elif chains — well below the native stack.
     let nodes = parse([]);
-    // Wrap the values in a root scope carrying the anchors, without mutating
-    // what the caller passed: by default `$` and `@` both point at the root.
-    // An embedder can override the anchors with a `{ root, item }` second arg:
-    // `$` = root, `@` = item (distinct objects). Omitting `item` leaves `@`
-    // unbound, so `@.x` throws through xprsn's guard — a group-header band that
-    // has no current row wants exactly that.
+    // The trusted-scope render, and the one render body: the caller's chain
+    // already carries the anchors, so no wrapper is created and nothing is
+    // written anywhere. One accumulator per render, owned here and threaded
+    // down. A registry function that renders another template gets its own,
+    // so re-entrancy needs no bookkeeping.
+    const scoped = (/** @type {any} */ values) => {
+      const acc = seed();
+      run(nodes, values, acc);
+      return take(acc);
+    };
+    // The default render wraps the values in a root scope carrying the
+    // anchors, without mutating what the caller passed: by default `$` and `@`
+    // both point at the root. An embedder can override the anchors with a
+    // `{ root, item }` second arg: `$` = root, `@` = item (distinct objects).
+    // Omitting `item` leaves `@` unbound, so `@.x` throws through xprsn's
+    // guard — a group-header band that has no current row wants exactly that.
     const f = (/** @type {any} */ values, /** @type {any} */ anchors) => {
       values = values || EMPTY;
       const r = Object.create(values);
       r["$"] = anchors ? anchors.root : values;
       r["@"] = anchors ? anchors.item : values;
-      // One accumulator per render, owned here and threaded down. A registry
-      // function that renders another template gets its own, so re-entrancy
-      // needs no bookkeeping.
-      const acc = seed();
-      run(nodes, r, acc);
-      return take(acc);
+      return scoped(r);
     };
     // Array.from, not a spread: the bundler's transpile turns `[...set]` into
     // `[].concat(set)`, which wraps the Set instead of unpacking it.
     f.names = Array.from(names);
+    f.reads = reads;
     f.functions = Array.from(functions);
+    // This compile's own `names` set doubles as its origin: every diagnostic
+    // thrown through this renderer was marked with it, at compile time by
+    // `fault` and at render time by the closures `compileExpr` built. Captured
+    // now — the module-level `names` moves on to the next compile.
+    const o = names;
+    f.isDiagnostic = (/** @type {unknown} */ x) => origin(x) === o;
+    f.scoped = scoped;
     return f;
   }
   return { template, render: (str, values, funcs) => template(str, funcs)(values) };

package/lib/html.d.ts

@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./type
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<string>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<string>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): string;

package/lib/html.js

@@ -3,19 +3,19 @@
  * 0.6's behaviour, kept for templates that target HTML directly. Everything
  * else in sjabloon is output-neutral; escaping lives here and nowhere else.
  */
-import { litNode, make } from "./core.js";
+import { display, litNode, make } from "./core.js";
 
 /** @type {Record<string, string>} */
 const ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
-/** @param {any} s */
-const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ESC[c]);
+/** @param {string} s Already display text — both call sites pass `display()`. */
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ESC[c]);
 
 export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
   litNode,
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += esc(value ?? ""))),
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += String(value ?? ""))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += esc(display(value)))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += display(value))),
   () => ({ text: "" }),
   (acc) => acc.text,
 ]);

package/lib/index.d.ts

@@ -11,13 +11,26 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<Token[]>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<Token[]>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): Token[];
 
 /**
  * Join a token stream into the string `sjabloon/text` would have produced:
- * literals verbatim, values as `String(value ?? '')`.
+ * literals verbatim, values through `display()`.
  */
 export function text(tokens: readonly Token[]): string;
+
+/**
+ * Display text for one interpolated value — the scalar rule `text()` and the
+ * string editions share. A valid `Date` renders as ISO 8601 UTC
+ * (`toISOString()`), deterministically across machines; an invalid `Date`
+ * stays `"Invalid Date"`; nullish displays empty; everything else is
+ * `String(value)`.
+ */
+export function display(value: unknown): string;

package/lib/index.js

@@ -4,9 +4,9 @@
  * so nothing here is HTML-aware and `{{{ }}}` has no meaning — `{{ }}` is
  * already raw.
  */
-import { make } from "./core.js";
+import { display, make } from "./core.js";
 
-export { isDiagnostic, relocate } from "./core.js";
+export { display, isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
   // Static text is a compile-time constant: hoist and freeze one token per
@@ -25,20 +25,18 @@ export const { template, render } = make([
 
 /**
  * Join a token stream into the string `sjabloon/text` would have produced:
- * literals verbatim, values as `String(value ?? '')`.
+ * literals verbatim, values through `display()` — the one scalar rule, so a
+ * `Date` joins as ISO 8601 UTC here exactly as the string editions render it.
  *
  * @param {readonly import('./types.js').Token[]} tokens A render's output.
  * @returns {string} The joined text.
  */
 export const text = (tokens) => {
   let s = "";
-  // One `?? ''` per token, so a literal never stringifies and a nullish value
-  // still renders empty. Widened here because each token carries one key or
-  // the other, which the public union deliberately does not model.
+  // A literal never stringifies and a nullish value still renders empty.
+  // Widened here because each token carries one key or the other, which the
+  // public union deliberately does not model.
   for (const t of /** @type {readonly { literal?: string, value?: unknown }[]} */ (tokens))
-    // Stringifying an arbitrary value is this helper's documented contract, so
-    // `no-base-to-string` is describing the feature rather than a mistake.
-    // oxlint-disable-next-line typescript/no-base-to-string
-    s += t.literal ?? String(t.value ?? "");
+    s += t.literal ?? display(t.value);
   return s;
 };

package/lib/text.d.ts

@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./type
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<string>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<string>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): string;

package/lib/text.js

@@ -6,13 +6,13 @@
  * Definitionally `text(template(str)(values))` from the root entry, but built
  * as a string accumulator so casual string users never allocate tokens.
  */
-import { litNode, make } from "./core.js";
+import { display, litNode, make } from "./core.js";
 
 export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
   litNode,
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += String(value ?? ""))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += display(value))),
   0,
   () => ({ text: "" }),
   (acc) => acc.text,

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { XprsnErrorCode } from "xprsn";
+import type { XprsnErrorCode, XprsnRead } from "xprsn";
 
 export type SjabloonErrorCode =
   | XprsnErrorCode
@@ -24,6 +24,13 @@ export interface SjabloonDiagnostic extends Error {
 }
 
 export type SjabloonValues = Record<string, any>;
+
+/**
+ * One root-name read, with its span in the template source — xprsn's read
+ * record, forwarded with only its coordinates shifted.
+ */
+export type SjabloonRead = XprsnRead;
+
 export type SjabloonFunctions = Record<string, Function>;
 
 /**
@@ -49,13 +56,29 @@ export interface SjabloonScope {
  * A compiled template: render it many times.
  *
  * `names` are the variables the template reads from your values, deduplicated;
- * loop variables the template introduces are not included. `functions` are the
- * registry functions the template calls, deduplicated.
+ * loop variables the template introduces are not included, and neither is
+ * anything the compile's `bound` option declared. `reads` are every root-name
+ * read with its span in the template source, in source order — duplicates,
+ * anchors, loop variables and bound names kept, so `names` is its free,
+ * deduplicated view. `functions` are the registry functions the template
+ * calls, deduplicated.
+ *
+ * `isDiagnostic(error)` recognizes runtime diagnostics thrown through this
+ * renderer alone — the per-renderer twin of the module-wide `isDiagnostic`.
+ *
+ * `scoped(values)` renders over a scope chain that already binds the anchors:
+ * no wrapper scope is created, `$` and `@` resolve from `values` itself, and a
+ * chain that omits `@` leaves it unbound so `@.x` throws through xprsn's
+ * guard. The zero-allocation seam for an embedder rendering over scopes it
+ * already builds; `{{#each}}` still re-points `@` inside its body.
  */
 export interface SjabloonRenderer<T> {
   (values?: SjabloonValues, scope?: SjabloonScope): T;
   names: string[];
+  reads: SjabloonRead[];
   functions: string[];
+  isDiagnostic(error: unknown): boolean;
+  scoped(values: SjabloonValues): T;
 }
 
 /** One static text run of the template, verbatim. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sjabloon",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
   "keywords": [
     "csp",
@@ -61,7 +61,7 @@
     "test:unit": "c8 --100 --src lib/ node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js"
   },
   "dependencies": {
-    "xprsn": "^0.10.0"
+    "xprsn": "^0.11.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
@@ -85,7 +85,7 @@
       "ignore": [
         "xprsn"
       ],
-      "limit": "2.25 kB"
+      "limit": "2.35 kB"
     },
     {
       "name": "sjabloon/text",
@@ -93,7 +93,7 @@
       "ignore": [
         "xprsn"
       ],
-      "limit": "2.25 kB"
+      "limit": "2.35 kB"
     },
     {
       "name": "sjabloon/html",
@@ -101,7 +101,7 @@
       "ignore": [
         "xprsn"
       ],
-      "limit": "2.3 kB"
+      "limit": "2.4 kB"
     }
   ],
   "engines": {