@optionfactory/fml 9.0.0-rc15 → 9.0.0-rc16

package/dist/ftl.mjs

@@ -1,10 +1,6 @@
 /**
- * A Map bounded by entry count, evicting in insertion order: not an LRU (a hit
- * does not refresh an entry), just a cap keeping unbounded key spaces (parsed
- * expressions, compiled masks, formatter instances) from growing forever. The
- * capacity is sized so eviction never happens on a sane page: hitting it means
- * dynamically generated keys, where FIFO's worst case (evicting a hot entry)
- * costs one recomputation.
+ * A Map bounded by entry count, evicting the oldest entry when full. A hit does
+ * not refresh an entry: eviction follows insertion order, not use.
  */
 class BoundedCache {
     #max;
@@ -33,6 +29,7 @@ class BoundedCache {
         this.#entries.set(key, value);
         return value;
     }
+    /** @returns {number} the number of entries held */
     get size() {
         return this.#entries.size;
     }
@@ -75,10 +72,6 @@ const nodes = {
 //
 // https://peggyjs.org/
 
-    //keyword classification lives here, not in the grammar's ordered choice: the
-    //identifier rule consumes the whole word and the action decides, so no keyword
-    //can grab a longer identifier's prefix. A Map, not a plain object: `in` on the
-    //latter would classify inherited names such as `constructor` as keywords
     const keywords = new Map([
         ['true', true],
         ['false', false],
@@ -3250,10 +3243,10 @@ function peg$parse(input, options) {
 /**
  * The one lookup against a data stack: the innermost overlay carrying the name
  * wins, `self` is the innermost overlay itself, and a function overlay counts
- * like an object one. Every lookup that resolves a name goes through this, so the
- * imperative facades cannot drift from what a template sees.
+ * like an object one.
  * @param {any[]} dataStack
  * @param {string|symbol} prop
+ * @returns {any} undefined when no overlay carries the name
  */
 const resolveInStack = (dataStack, prop) => {
     if (prop === 'self') {
@@ -3317,8 +3310,7 @@ class EvaluatingVisitor {
         return this.visit(node.lhs) || this.visit(node.rhs);
     }
     [nodes.nullc](node) {
-        const lhs = this.visit(node.lhs);
-        return lhs !== null && lhs !== undefined ? lhs : this.visit(node.rhs);
+        return this.visit(node.lhs) ?? this.visit(node.rhs);
     }
     [nodes.not](node) {
         return !this.visit(node.expr);
@@ -3385,8 +3377,7 @@ class EvaluatingVisitor {
         return this.visit(node.cond) ? this.visit(node.ifTrue) : this.visit(node.ifFalse);
     }
     [nodes.elv](node) {
-        const cond = this.visit(node.cond);
-        return cond ? cond : this.visit(node.ifFalse);
+        return this.visit(node.cond) || this.visit(node.ifFalse);
     }
     [nodes.access](node) {
         let prev;
@@ -3452,16 +3443,23 @@ class EvaluatingVisitor {
  * spliced into the expression text.
  */
 class Expressions {
+    /** Parses the whole text as one expression: `user.name`. */
     static MODE_EXPRESSION = Symbol('MODE_EXPRESSION');
+    /**
+     * Parses text with interpolations, `Hello {{ user.name }}`, evaluating to
+     * its parts: `{ type, value }` for each literal run and each `{{ }}` (text),
+     * `{{{ }}}` (html) or `{{{{ }}}}` (node) interpolation, in order.
+     */
     static MODE_TEMPLATED = Symbol('MODE_TEMPLATED');
 
     static #astCache = new BoundedCache(1000);
 
     /**
-     * Parses an expression.
+     * Parses an expression, caching the ast by mode and text.
      * @param {string} expression
-     * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode]
-     * @returns the ast
+     * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] MODE_EXPRESSION when omitted
+     * @returns {any} the ast
+     * @throws a peggy syntax error when the text does not parse
      */
     static parse(expression, mode) {
         const key = mode?.toString() + expression;
@@ -3472,12 +3470,12 @@ class Expressions {
         );
     }
     /**
-     * Evaluates an expression.
+     * Evaluates a parsed ast against the modules and the data stack.
      * @param {{[k: string]: any } | null | undefined } modules
-     * @param {any[]} dataStack
-     * @param {any} ast
-     * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode]
-     * @returns the result
+     * @param {any[]} dataStack innermost overlay last
+     * @param {any} ast what `parse` answered
+     * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] the mode it was parsed in
+     * @returns {any} the value, or the list of parts in MODE_TEMPLATED
      */
     static evaluate(modules, dataStack, ast, mode) {
         return new EvaluatingVisitor(modules, dataStack).visitRoot(ast, mode === Expressions.MODE_TEMPLATED);
@@ -3485,10 +3483,10 @@ class Expressions {
     /**
      * Parses and evaluates an expression.
      * @param {{ [x: string]: any; } | null | undefined} modules
-     * @param {any[]} dataStack
+     * @param {any[]} dataStack innermost overlay last
      * @param {string} expression
-     * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode]
-     * @returns the result
+     * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] MODE_EXPRESSION when omitted
+     * @returns {any} the value, or the list of parts in MODE_TEMPLATED
      */
     static interpret(modules, dataStack, expression, mode) {
         return Expressions.evaluate(modules, dataStack, Expressions.parse(expression, mode), mode);
@@ -3504,14 +3502,31 @@ class Expressions {
 class ExpressionEvaluator {
     #modules;
     #dataStack;
+    /**
+     * @param {{ [k: string]: any } | null | undefined} modules
+     * @param {any[]} dataStack innermost overlay last
+     */
     constructor(modules, dataStack) {
         this.#modules = modules;
         this.#dataStack = dataStack;
     }
+    /**
+     * A new evaluator with one more module: `#name:fn()` resolves into it, and an
+     * empty name merges a whole map whose functions resolve bare, as `#fn()`.
+     * @param {string} name
+     * @param {object} value
+     * @returns {ExpressionEvaluator}
+     */
     withModule(name, value) {
         const module = name ? { [name]: value } : value;
         return new ExpressionEvaluator({ ...this.#modules, ...module }, this.#dataStack);
     }
+    /**
+     * A new evaluator with the data pushed as the innermost overlays, the last
+     * one winning a shared name.
+     * @param {...any} data
+     * @returns {ExpressionEvaluator}
+     */
     withOverlay(...data) {
         return new ExpressionEvaluator(
             this.#modules,
@@ -3522,26 +3537,36 @@ class ExpressionEvaluator {
      * Resolves a name against the data stack, with no parse round trip: the
      * lookup a template's bare identifier makes, for an imperative caller.
      * @param {string} name
+     * @returns {any} undefined when no overlay carries the name
      */
     resolve(name) {
         return resolveInStack(this.#dataStack, name);
     }
-    /** Evaluates an expression against this scope. */
+    /**
+     * Evaluates an expression against this scope.
+     * @param {string} expression
+     * @returns {any}
+     */
     evaluateExpression(expression) {
         return Expressions.interpret(this.#modules, this.#dataStack, expression, Expressions.MODE_EXPRESSION);
     }
-    /** Evaluates a templated text, the `{{ }}` form, against this scope. */
+    /**
+     * Evaluates a templated text, the `{{ }}` form, against this scope.
+     * @param {string} text
+     * @returns {{ type: symbol, value: any }[]} its parts, as MODE_TEMPLATED describes
+     */
     evaluateTemplated(text) {
         return Expressions.interpret(this.#modules, this.#dataStack, text, Expressions.MODE_TEMPLATED);
     }
 }
 
-/** Creates and inspects the DocumentFragments a Template renders into. */
+/** Creates, serializes and inspects DocumentFragments. */
 class Fragments {
     /**
-     * Creates a DocumentFragment from an string.
-     * @param  {...string} html
-     * @returns {DocumentFragment} the fragment
+     * Parses html into a DocumentFragment adopted by the document, each piece
+     * trimmed and the pieces joined.
+     * @param {...string} html
+     * @returns {DocumentFragment}
      */
     static fromHtml(...html) {
         const el = document.createElement('template');
@@ -3549,11 +3574,11 @@ class Fragments {
         return document.adoptNode(el.content);
     }
     /**
-     * Creates a string representation (HTML) of a DocumentFragment, consuming it:
-     * the nodes are moved out, not copied, and the fragment is left empty. Pass
+     * Serializes a fragment, or a single node, to html, consuming it: the nodes
+     * are moved out, not copied, and a fragment is left empty. Pass
      * `fragment.cloneNode(true)` to keep the original usable.
-     * @param {DocumentFragment} fragment
-     * @returns {string} the html
+     * @param {DocumentFragment|Node} fragment
+     * @returns {string}
      */
     static toHtml(fragment) {
         var el = document.createElement('template');
@@ -3561,17 +3586,17 @@ class Fragments {
         return el.innerHTML;
     }
     /**
-     * Checks if a fragment contains only blank text nodes
+     * Whether a fragment holds no element and no text but whitespace.
      * @param {DocumentFragment} fragment
-     * @returns {boolean} true if the fragment is blank
+     * @returns {boolean}
      */
     static isBlank(fragment) {
         return fragment.childElementCount === 0 && fragment.textContent.trim() === '';
     }
     /**
-     * Creates a DocumentFragment from nodes.
-     * @param  {...Node} nodes
-     * @returns {DocumentFragment} the fragment
+     * Moves the nodes, in order, into a new DocumentFragment.
+     * @param {...Node} nodes
+     * @returns {DocumentFragment}
      */
     static from(...nodes) {
         const fragment = new DocumentFragment();
@@ -3581,9 +3606,10 @@ class Fragments {
         return fragment;
     }
     /**
-     * Creates a DocumentFragment from childNodes of an element.
+     * Moves the children of a node into a new DocumentFragment, leaving the
+     * node empty.
      * @param {Node} el
-     * @returns {DocumentFragment} the fragment
+     * @returns {DocumentFragment}
      */
     static fromChildNodes(el) {
         const fragment = new DocumentFragment();
@@ -3594,23 +3620,23 @@ class Fragments {
     }
 }
 
-/** Attribute reads and writes where a nullish value removes the attribute instead of setting it to the string 'null'. */
+/** Attribute helpers: unique ids, defaults, prefixed forwarding, and writes where a nullish value removes the attribute. */
 class Attributes {
     static id = 0;
     /**
-     * Creates a unique id with the given prefix.
+     * A page-unique id under the prefix, as `prefix-n`.
      * @param {string} prefix
-     * @returns
+     * @returns {string}
      */
     static uid(prefix) {
         return `${prefix}-${++Attributes.id}`;
     }
     /**
-     * Sets an attribute if not present.
+     * Sets an attribute when the element does not carry it.
      * @param {Element} el
      * @param {string} k
      * @param {string} v
-     * @returns
+     * @returns {string|null} the attribute's value afterwards
      */
     static defaultValue(el, k, v) {
         if (!el.hasAttribute(k)) {
@@ -3619,7 +3645,9 @@ class Attributes {
         return el.getAttribute(k);
     }
     /**
-     * Forwards prefixed attributes from an element to another (removing the prefix).
+     * Copies every attribute whose name starts with the prefix onto another
+     * element, under the name without the prefix. `<prefix>class` adds its
+     * classes to the target's instead of replacing them.
      * @param {string} prefix
      * @param {Element} from
      * @param {Element} to
@@ -3642,7 +3670,7 @@ class Attributes {
             });
     }
     /**
-     * Sets the value of an attribute. nullish values remove the attribute.
+     * Sets an attribute, or removes it when the value is nullish.
      * @param {Element} el
      * @param {string} attr
      * @param {string | null | undefined} value
@@ -3664,13 +3692,14 @@ class Attributes {
  */
 class LightSlots {
     /**
-     * Extracts light slots from an element. For non default slots in a template tag, the content is extracted.
+     * Takes an element's children apart into slots, leaving the element empty.
+     * A named child is removed and contributes what `slotFromNode` answers;
+     * children sharing a name are gathered in order. A child with an empty
+     * `slot` belongs to the default slot, in document order among the rest.
      * @param {Element} el
-     * @returns the slots
+     * @returns {Record<string, DocumentFragment>} the slots by name, `default` always present
      */
     static from(el) {
-        //the platform reads slot="" as the default slot: such children stay in
-        //the document order of the default content, their claim stripped like any named one
         for (const child of el.children) {
             if (child.matches('[slot=""]')) {
                 child.removeAttribute('slot');
@@ -3696,6 +3725,12 @@ class LightSlots {
         }
         return slots;
     }
+    /**
+     * What a slotted node contributes: a template's content, the parsed markup
+     * of a `<script type="text/html">`, or the node itself.
+     * @param {Element} el
+     * @returns {Element|DocumentFragment}
+     */
     static slotFromNode(el) {
         if (el instanceof HTMLTemplateElement) {
             return document.adoptNode(el.content);
@@ -3707,12 +3742,13 @@ class LightSlots {
     }
 }
 
-/** Waits for the parser and for the document, for elements that upgrade before their own markup is complete. */
+/** Waits on the parser and the document, and queries an element's own children. */
 class Nodes {
     /**
-     * Checks if an element is already parsed.
+     * Whether the parser has moved past the element: the element, or one of
+     * its ancestors, has a next sibling.
      * @param {Element} el
-     * @returns
+     * @returns {boolean}
      */
     static isParsed(el) {
         for (let c = /** @type {Node | null} */ (el); c; c = c.parentNode) {
@@ -3724,13 +3760,12 @@ class Nodes {
     }
 
     /**
-     * Waits for the document's DOMContentLoaded, resolving immediately when
-     * that moment already passed. 'interactive' alone cannot tell a document
-     * still waiting for deferred scripts (the event comes, however late) from
-     * a module imported past it (the event is gone): the two events order
-     * themselves, DOMContentLoaded always precedes load, so racing the two
-     * resolves with DCL whenever it is still coming and with load otherwise,
-     * never early.
+     * Waits for the document's DOMContentLoaded. Resolves at once when that
+     * moment already passed, and for a document with no view, which receives
+     * no events. Never resolves early for a document still running its
+     * deferred scripts.
+     * @param {Document} doc
+     * @returns {Promise<void>}
      */
     static waitDomContentLoaded(doc) {
         if (doc.readyState === 'loading') {
@@ -3743,7 +3778,6 @@ class Nodes {
         }
         const win = doc.defaultView;
         if (win === null) {
-            //a viewless document can receive no event at all
             return Promise.resolve();
         }
         return new Promise((resolve) => {
@@ -3763,18 +3797,8 @@ class Nodes {
      * which is the parser having moved past this subtree. The document's
      * DOMContentLoaded is the deadline. Resolves immediately for an element
      * that is already parsed.
-     *
-     * Every ancestor is watched, not only the parent, because that is what the
-     * predicate reads: an element last among its siblings becomes parsed when
-     * an ancestor gains one, and a childList observer on the parent never sees
-     * that. Formatted markup usually hides the difference, the whitespace
-     * before a closing tag being a text node the parent does gain, so the gap
-     * shows on whitespace-free markup, where the wait fell back to the
-     * deadline. One observer takes many targets, so the cost is one observe()
-     * per level, and it is disconnected at the first checkpoint past the
-     * element either way.
-     * @param {any} el
-     * @returns {Promise<any>}
+     * @param {Element} el
+     * @returns {Promise<Element>} the element
      */
     static waitParsed(el) {
         if (Nodes.isParsed(el)) {
@@ -3799,10 +3823,10 @@ class Nodes {
     }
 
     /**
-     * Returns the first child of the element element (if exists) matching the selector.
-     * @param {Element} el
+     * The first child element matching the selector, descendants excluded.
+     * @param {Element|DocumentFragment} el
      * @param {string} selector
-     * @returns
+     * @returns {Element|null}
      */
     static queryChildren(el, selector) {
         for (const c of el.children) {
@@ -3813,10 +3837,10 @@ class Nodes {
         return null;
     }
     /**
-     * Returns all children of the element matching the selector.
-     * @param {Element} el
+     * Every child element matching the selector, descendants excluded.
+     * @param {Element|DocumentFragment} el
      * @param {string} selector
-     * @returns
+     * @returns {Element[]}
      */
     static queryChildrenAll(el, selector) {
         const r = [];
@@ -3873,9 +3897,11 @@ class NodeOperations {
 
 /** The `data-tpl-*` commands, each taking the node it is written on and the scope it evaluates in. */
 class CommandsHandler {
-    //the order is the semantics: each command sees the node as the ones before
-    //it left it, so tplIf gates before tplWith/tplEach push their overlay and
-    //tplWhen gates after (inside the sub-render, where the overlay is in scope)
+    /**
+     * The order the commands run in on one element, each seeing the node as the
+     * ones before left it: tplIf gates before tplWith and tplEach push their
+     * overlay, tplWhen gates after, inside the scope that overlay opened.
+     */
     static ORDERED_COMMANDS = [
         'tplIf',
         'tplWith',
@@ -3886,8 +3912,7 @@ class CommandsHandler {
         'tplRemove',
         'tplVerbatim',
     ];
-    //same body as tplWhen: the two differ only in ORDERED_COMMANDS position,
-    //if evaluates in the outer scope, before with/each
+    /** Removes the node when the expression is falsy, evaluated before tplWith and tplEach open their overlay. */
     static tplIf(node, expression, ops, evaluator) {
         const accept = evaluator.evaluateExpression(expression);
         if (!accept) {
@@ -3902,49 +3927,36 @@ class CommandsHandler {
             .render();
         ops.replace(node, newNode);
     }
+    /**
+     * Renders the node once per entry, in place of the node. A Map iterates as
+     * `{ key, value }` entries in its own order, a plain object as `{ key, value }`
+     * entries in `Object.entries` order, and any other iterable as itself; a
+     * value that is none of these throws. Each render sees its entry under
+     * `data-tpl-var`, or as the whole overlay without one. `data-tpl-stat` names
+     * an overlay beneath the entry carrying `index`, `count`, `size`, `first`,
+     * `last`, `even` and `odd`, so an entry property of the same name wins; the
+     * size, and so `last`, is null for a collection that knows neither its
+     * `length` nor its `size`, which is never consumed to learn it.
+     */
     static tplEach(node, expression, ops, evaluator) {
         const varName = ops.popData(node, 'tplVar');
         const statName = ops.popData(node, 'tplStat');
         const template = new Template(node, evaluator);
         const evaluated = evaluator.evaluateExpression(expression);
-        //keyed collections iterate as {key, value} entries: a Map in its own
-        //order, a non-iterable plain dict in Object.entries order. Plain alone:
-        //a class instance or a response wrapper standing where an array was
-        //expected still fails loudly below, and any other iterable (a Set, a
-        //generator, an entries() iterator) iterates as itself
         const proto = evaluated === null || typeof evaluated !== 'object' ? undefined : Object.getPrototypeOf(evaluated);
-        const keyed =
-            evaluated instanceof Map
-                ? [...evaluated]
-                : !evaluated?.[Symbol.iterator] && (proto === Object.prototype || proto === null)
-                  ? Object.entries(evaluated)
-                  : null;
+        const plain = !evaluated?.[Symbol.iterator] && (proto === Object.prototype || proto === null);
+        const dict = plain ? Object.entries(evaluated) : null;
+        const keyed = evaluated instanceof Map ? [...evaluated] : dict;
         const entries = keyed === null ? evaluated : keyed.map(([key, value]) => ({ key, value }));
         if (!entries?.[Symbol.iterator]) {
             throw new Error(`Expected an iterable got '${evaluated}'`);
         }
-        if (!statName) {
-            for (const v of entries) {
-                ops.prepend(node, template.withOverlay(varName ? { [varName]: v } : v).render());
-            }
-            ops.remove(node);
-            return;
-        }
-        //the stat rides grouped under its declared name, overlaid below the
-        //item, so data can never collide with its fields and an item property
-        //sharing the stat's very name wins, as data always does. The size is
-        //read where the collection already knows it (arrays and keyed entries
-        //by length, sets and the like by size): an arbitrary iterator is never
-        //consumed to learn it, so its size and last read null, the unknown
-        const size = Array.isArray(entries)
-            ? entries.length
-            : typeof entries.length === 'number'
-              ? entries.length
-              : typeof entries.size === 'number'
-                ? entries.size
-                : null;
+        const measured = statName ? entries : null;
+        const counted = typeof measured?.length === 'number' ? measured.length : measured?.size;
+        const size = typeof counted === 'number' ? counted : null;
         let index = 0;
         for (const v of entries) {
+            const item = varName ? { [varName]: v } : v;
             const stat = {
                 index,
                 count: index + 1,
@@ -3954,16 +3966,13 @@ class CommandsHandler {
                 even: index % 2 === 0,
                 odd: index % 2 === 1,
             };
-            ops.prepend(
-                node,
-                template.withOverlay({ [statName]: stat }, varName ? { [varName]: v } : v).render(),
-            );
+            const layers = statName ? [{ [statName]: stat }, item] : [item];
+            ops.prepend(node, template.withOverlay(...layers).render());
             ++index;
         }
         ops.remove(node);
     }
-    //same body as tplIf: the two differ only in ORDERED_COMMANDS position,
-    //when evaluates after with/each, in the scope their overlay opened
+    /** Removes the node when the expression is falsy, evaluated in the overlay tplWith or tplEach opened. */
     static tplWhen(node, expression, ops, evaluator) {
         const accept = evaluator.evaluateExpression(expression);
         if (!accept) {
@@ -3977,12 +3986,8 @@ class CommandsHandler {
     static tplRemove(node, value, ops, evaluator) {
         switch (value.toLowerCase()) {
             case 'tag': {
-                const fragment = new DocumentFragment();
-                while (node.firstChild) {
-                    fragment.appendChild(node.firstChild);
-                }
+                const fragment = Fragments.fromChildNodes(node);
                 if ('tplVerbatim' in node.dataset) {
-                    //we are removing the parent element so we have to handle the lower priority commands
                     ops.popData(node, 'tplVerbatim');
                     ops.replace(node, fragment);
                 } else {
@@ -4045,12 +4050,10 @@ class CommandsHandler {
     }
 }
 
-// Module-isolated string cache for dataset-to-attribute conversions
 const attributeCache = new BoundedCache(1000);
 
 /**
- * Converts a tpl camelCase dataset key into a kebab-case attribute name.
- * Uses a cache lookup to avoid repetitive regex/string splitting.
+ * The attribute a `tpl` dataset key targets: `tplAriaLabel` is `aria-label`.
  * @param {string} dataSetKey
  * @returns {string}
  */
@@ -4072,38 +4075,40 @@ function toAttr(dataSetKey) {
  */
 class Template {
     /**
-     * Creates a template from a string.
+     * Creates a template from html.
      * @param {string} html
      * @param {{ [k: string] : any }?} [modules]
-     * @param {...*} data
-     * @returns the template
+     * @param {...*} data the data stack, innermost last
+     * @returns {Template}
      */
     static fromHtml(html, modules, ...data) {
         return new Template(Fragments.fromHtml(html), new ExpressionEvaluator(modules, data));
     }
 
     /**
-     * Creates a template from the content of the first template element matching the selector.
+     * Creates a template from the content of the first element matching the
+     * selector, which is adopted: the template element is left empty.
      * @param {string} selector for an HTMLTemplateElement
      * @param {{ [k: string] : any }?} [modules]
-     * @param {...*} data
-     * @returns the template
+     * @param {...*} data the data stack, innermost last
+     * @returns {Template}
+     * @throws when the selector matches no template element
      */
     static fromSelector(selector, modules, ...data) {
         const templateEl = document.querySelector(selector);
         if (!(templateEl instanceof HTMLTemplateElement)) {
             throw new Error('template selector does not match any template tag');
         }
-        const fragment = document.adoptNode(templateEl.content);
-        return new Template(fragment, new ExpressionEvaluator(modules, data));
+        return Template.fromTemplate(templateEl, modules, ...data);
     }
 
     /**
-     * Creates a template from the content of an HTMLTemplateElement.
+     * Creates a template from the content of a template element, which is
+     * adopted: the template element is left empty.
      * @param {HTMLTemplateElement} templateEl
      * @param {{ [k: string] : any }?} [modules]
-     * @param {...*} data
-     * @returns the template
+     * @param {...*} data the data stack, innermost last
+     * @returns {Template}
      */
     static fromTemplate(templateEl, modules, ...data) {
         const fragment = document.adoptNode(templateEl.content);
@@ -4111,11 +4116,12 @@ class Template {
     }
 
     /**
-     * Creates a template from a DocumentFragment.
+     * Creates a template over a fragment, which is imported afresh on every
+     * render and never modified.
      * @param {DocumentFragment} fragment
      * @param { { [k: string] : any }? } [modules]
-     * @param {...*} data
-     * @returns the template
+     * @param {...*} data the data stack, innermost last
+     * @returns {Template}
      */
     static fromFragment(fragment, modules, ...data) {
         return new Template(fragment, new ExpressionEvaluator(modules, data));
@@ -4135,28 +4141,32 @@ class Template {
      * Creates a new Template rendering in another scope: the one way to rebind
      * a compiled template to a registry's modules and data.
      * @param {ExpressionEvaluator} evaluator
+     * @returns {Template}
      */
     withEvaluator(evaluator) {
         return new Template(this.#fragment, evaluator);
     }
     /**
-     * Creates a new Template replacing the fragment.
+     * Creates a new Template over another fragment, in the same scope.
      * @param {DocumentFragment} fragment
+     * @returns {Template}
      */
     withFragment(fragment) {
         return new Template(fragment, this.#evaluator);
     }
     /**
-     * Creates a new Template with a new module added.
+     * Creates a new Template with a module added, as `ExpressionEvaluator.withModule` does.
      * @param {string?} name
      * @param {{[k: string]: any}} value
+     * @returns {Template}
      */
     withModule(name, value) {
         return new Template(this.#fragment, this.#evaluator.withModule(name, value));
     }
     /**
-     * Creates a new Template with new a data overlay added to the stack.
+     * Creates a new Template with the data pushed as the innermost overlays.
      * @param {...*} data
+     * @returns {Template}
      */
     withOverlay(...data) {
         return new Template(this.#fragment, this.#evaluator.withOverlay(...data));
@@ -4165,7 +4175,7 @@ class Template {
      * Evaluates an expression in this template's scope, widened by the overlays.
      * @param {string} expression
      * @param {...*} data
-     * @returns the evaluated expression result
+     * @returns {any}
      */
     evaluateExpression(expression, ...data) {
         return this.#evaluator.withOverlay(...data).evaluateExpression(expression);
@@ -4174,33 +4184,29 @@ class Template {
      * Evaluates a templated text, the `{{ }}` form, in this template's scope.
      * @param {string} text
      * @param {...*} data
-     * @returns the parts the text evaluates to
+     * @returns {{ type: symbol, value: any }[]} the parts, as `Expressions.MODE_TEMPLATED` describes
      */
     evaluateTemplated(text, ...data) {
         return this.#evaluator.withOverlay(...data).evaluateTemplated(text);
     }
     /**
-     * Returns an expression evaluator with bound modules and dataStack.
+     * The scope this template renders in.
+     * @returns {ExpressionEvaluator}
      */
     evaluator() {
         return this.#evaluator;
     }
     /**
-     * Renders the template.
-     * @returns a DocumentFragment
+     * Renders the template into a new fragment, applying the `data-tpl-*`
+     * commands and bindings and the `{{ }}` interpolations.
+     * @returns {DocumentFragment}
+     * @throws {RenderError} naming the node and the directive that failed
      */
     render() {
         try {
             const ops = new NodeOperations();
             const imported = document.importNode(this.#fragment, true);
-            const fragment =
-                imported.nodeType === Node.DOCUMENT_FRAGMENT_NODE
-                    ? imported
-                    : (() => {
-                          const d = new DocumentFragment();
-                          d.appendChild(imported);
-                          return d;
-                      })();
+            const fragment = imported.nodeType === Node.DOCUMENT_FRAGMENT_NODE ? imported : Fragments.from(imported);
             const iterator = document.createNodeIterator(
                 fragment,
                 NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
@@ -4226,8 +4232,6 @@ class Template {
                     try {
                         CommandsHandler[command](el, value, ops, this.#evaluator);
                     } catch (ex) {
-                        //the directive is popped before it runs, so the open tag no
-                        //longer carries it: the frame names it and its expression
                         throw RenderError.wrap(`Error evaluating data-tpl-${toAttr(command)}="${value}"`, el, ex);
                     }
                     if (ops.removed(el)) {
@@ -4250,17 +4254,13 @@ class Template {
                             el.setAttribute(attributeName, evaluated);
                         }
                     } catch (ex) {
-                        throw RenderError.wrap(`Error evaluating data-tpl-${toAttr(dataSetKey)}="${expression}"`, el, ex);
+                        throw RenderError.wrap(`Error evaluating data-tpl-${attributeName}="${expression}"`, el, ex);
                     }
                 }
             }
             ops.cleanup();
             return fragment;
         } catch (ex) {
-            //a command, a text node or a nested render already named the node it
-            //failed on: wrapping again would add a frame for the fragment that
-            //contains it, one per level, serializing the whole template into the
-            //message that survives. Only a failure outside those is framed here
             if (ex instanceof RenderError) {
                 throw ex;
             }
@@ -4268,22 +4268,26 @@ class Template {
         }
     }
     /**
-     * Renders this template on the Element (replacing children).
+     * Renders this template into the element, replacing its children.
      * @param {Element} el
+     * @throws {RenderError}
      */
     renderTo(el) {
         el.replaceChildren(this.render());
     }
     /**
-     * Renders this template appending the resulting fragment to the Element.
+     * Renders this template and appends the result to the element.
      * @param {Element} el
+     * @throws {RenderError}
      */
     appendTo(el) {
         el.appendChild(this.render());
     }
     /**
-     * Renders this template on the first Element matching the selector (replacing children), if exists.
+     * Renders this template into the first element matching the selector,
+     * replacing its children; does nothing when none matches.
      * @param {string} selector
+     * @throws {RenderError}
      */
     renderToSelector(selector) {
         const el = document.querySelector(selector);
@@ -4292,8 +4296,10 @@ class Template {
         }
     }
     /**
-     * Renders this template appending the resulting fragment to the Element matching the selector, if exists.
+     * Renders this template and appends the result to the first element
+     * matching the selector; does nothing when none matches.
      * @param {string} selector
+     * @throws {RenderError}
      */
     appendToSelector(selector) {
         const el = document.querySelector(selector);
@@ -4317,30 +4323,26 @@ class Template {
 }
 
 /**
- * A render failure, one frame per nesting level. Each frame names the node it
- * failed on and what was being evaluated there, so the chain reads as the path
- * from the template's root down to the offending expression. The frame carries
- * the node's identification only, an open tag rather than its whole subtree:
- * the markup is serialized on demand through `html`, and the live node stays on
- * `node`, so a failure costs no clone and a nested failure does not embed the
- * page in its own message.
+ * A render failure, one frame per nesting level, chained through `cause` from
+ * the outermost frame down to the error that failed the expression. A frame's
+ * message names what was being evaluated and the node's open tag, with the
+ * attributes it still carries: the directive being evaluated is already off
+ * the tag. The subtree is not in the message; `html` serializes it on demand.
  */
 class RenderError extends Error {
-    /**
-     * How many frames a chain keeps. The innermost are the specific ones, so a
-     * deeper nesting drops the outer context rather than the failure site: three
-     * frames name the offending node and the two levels that hold it, which is
-     * the path a reader follows without the page arriving with it.
-     */
+    /** How many frames a chain keeps: a deeper nesting drops the outermost ones and marks the chain `truncated`. */
     static FRAMES = 3;
     #node;
     #depth;
-    /** true when the budget dropped the outer frames of this chain */
+    /** Whether the chain dropped outer frames to stay within FRAMES. */
     truncated = false;
     /**
-     * Frames a failure, unless the chain already spent its budget: then the
-     * cause travels on, marked so a report can say the outer context was
-     * dropped.
+     * Frames a failure, unless the chain already holds FRAMES frames: then the
+     * cause is returned as it is, marked `truncated`.
+     * @param {string} message
+     * @param {Node} nodeOrFragment the node that failed
+     * @param {any} cause
+     * @returns {RenderError}
      */
     static wrap(message, nodeOrFragment, cause) {
         if (cause instanceof RenderError && cause.depth >= RenderError.FRAMES) {
@@ -4349,27 +4351,44 @@ class RenderError extends Error {
         }
         return new RenderError(message, nodeOrFragment, cause);
     }
+    /**
+     * @param {string} message
+     * @param {Node} nodeOrFragment the node that failed
+     * @param {any} cause
+     */
     constructor(message, nodeOrFragment, cause) {
         super(`${message} in \`${RenderError.describe(nodeOrFragment)}\``, { cause });
         this.name = 'RenderError';
         this.#node = nodeOrFragment;
         this.#depth = (cause instanceof RenderError ? cause.depth : 0) + 1;
     }
-    /** How many frames this chain carries, this one included. */
+    /**
+     * How many frames this chain carries, this one included.
+     * @returns {number}
+     */
     get depth() {
         return this.#depth;
     }
-    /** The node the render failed on, live: it keeps its place in the fragment being built. */
+    /**
+     * The node the render failed on, live in the fragment being built.
+     * @returns {Node}
+     */
     get node() {
         return this.#node;
     }
-    /** The node's markup, serialized when asked for rather than on every failure. */
+    /**
+     * The failed node's markup, whitespace trimmed, serialized on each read.
+     * @returns {string}
+     */
     get html() {
         return RenderError.stringify(this.#node);
     }
     /**
      * What identifies a node in a frame: an element by its open tag, a text node
-     * by its source, a fragment by the open tags of the elements it holds.
+     * by its source, a fragment by the open tags of the elements it holds, cut
+     * at 120 characters.
+     * @param {Node} nodeOrFragment
+     * @returns {string}
      */
     static describe(nodeOrFragment) {
         if (nodeOrFragment.nodeType === Node.TEXT_NODE) {
@@ -4388,10 +4407,13 @@ class RenderError extends Error {
     static #ellipsize(text) {
         return text.length > 120 ? `${text.slice(0, 120)}…` : text;
     }
+    /**
+     * A node's markup with its whitespace-only text dropped and the rest trimmed.
+     * @param {Node} nodeOrFragment left untouched: a clone is serialized
+     * @returns {string}
+     */
     static stringify(nodeOrFragment) {
-        const t = document.createElement('template');
-        t.content.appendChild(RenderError.#cleanup(nodeOrFragment.cloneNode(true)));
-        return t.innerHTML;
+        return Fragments.toHtml(RenderError.#cleanup(nodeOrFragment.cloneNode(true)));
     }
     static #cleanup(node) {
         if (node.nodeType === Node.TEXT_NODE) {
@@ -4413,11 +4435,6 @@ class RenderError extends Error {
     }
 }
 
-/**
- * Tracks the elements waiting to render. `ready` resolves once the queue has
- * drained and never rejects; the promise kept per element resolves when that
- * element has rendered and rejects with whatever its upgrade threw.
- */
 class UpgradeQueue {
     #q = new Map();
     #readyResolve;
@@ -4429,12 +4446,6 @@ class UpgradeQueue {
             this.#start();
         });
     }
-    /**
-     * Waits for the page's readiness: the promise resolves right after the
-     * ftl:ready event is dispatched, and immediately when that moment already
-     * passed.
-     * @returns {Promise<void>}
-     */
     ready() {
         return this.#ready;
     }
@@ -4450,13 +4461,8 @@ class UpgradeQueue {
     }
     enqueue(el) {
         if (this.#q.has(el)) {
-            //already upgrading, can happen when disconnecting an element
-            //while it's already queued for upgrade (e.g.: ful-form)
             return;
         }
-        //one entry, two signals: readiness waits on a signal that only ever
-        //resolves, so nothing here attaches a rejection handler to the upgrade
-        //itself and a component that fails is still reported the way it always was
         const { promise: finished, resolve: markFinished } = /** @type {PromiseWithResolvers<void>} */ (
             Promise.withResolvers()
         );
@@ -4468,11 +4474,6 @@ class UpgradeQueue {
             });
         this.#q.set(el, { upgrade, finished });
     }
-    /**
-     * The one fixed-point loop: drains the accepted entries, including the ones
-     * enqueued while waiting, since a component is only queued once its parent
-     * connects it and a single pass would miss everything nested.
-     */
     async #drain(accept, pick) {
         for (;;) {
             const pending = Array.from(this.#q)
@@ -4485,22 +4486,25 @@ class UpgradeQueue {
         }
     }
     /**
-     * Waits for the whole queue to drain. Never rejects: a component that fails
-     * does not hold the others back, and readiness means the queue drained rather
-     * than that everything worked.
+     * Waits for the whole queue to drain, the upgrades enqueued meanwhile included.
+     * Never rejects: a failed upgrade counts as drained.
+     * @returns {Promise<void>}
      */
     settled() {
         return this.#drain(() => true, (entry) => entry.finished);
     }
-    /** Waits for the accepted upgrades, rejecting with the first that failed. */
+    /**
+     * Waits for the accepted upgrades, the ones enqueued meanwhile included,
+     * rejecting with the first that failed.
+     * @param {(el: Element) => boolean} accept
+     * @returns {Promise<void>}
+     */
     upgraded(accept) {
         return this.#drain(accept, (entry) => entry.upgrade);
     }
-    /** The pending upgrade of one element, undefined when it is not queued. */
     whenUpgraded(el) {
         return this.#q.get(el)?.upgrade;
     }
-    /** The elements whose upgrade is still pending, in queue order. */
     pending() {
         return Array.from(this.#q.keys());
     }
@@ -4511,8 +4515,8 @@ class UpgradeQueue {
  * and attribute mappers. Elements defined before configure() are deferred and
  * defined by it; from then on every defineElement takes effect immediately.
  * The exported `registry` singleton is the page's own; a `new Registry()` is a
- * separate instance, and Rendering and the ftl:ready machinery wait on the
- * singleton alone.
+ * separate instance with its own upgrade queue, which dispatches its own
+ * ftl:ready on the document, while Rendering waits on the singleton alone.
  */
 class Registry {
     #tagToClass = {};
@@ -4581,9 +4585,12 @@ class Registry {
      * Registers a custom element under its tag: the class is augmented with its
      * BITS (observed attributes, mappers, templates) and handed to the platform.
      * Before configure() the definition is deferred, so import order never
-     * matters.
+     * matters. The element resolves its templates and components through this
+     * registry, whichever one a module imports, and its `static config` is read
+     * here, so a page replacing it does so before the definition.
      * @param {string} tag
      * @param {*} klass a ParsedElement subclass
+     * @returns {Registry} this registry
      */
     defineElement(tag, klass) {
         if (!this.#configured) {
@@ -4601,13 +4608,8 @@ class Registry {
      * ancestors', so a base class declares what every subclass keeps observing
      * (a protocol attribute such as Field's disabled claim) and a leaf refines a
      * mapping, or moves a name's position, without repeating the whole list.
-     *
-     * The walk stops where the platform's own class hierarchy begins: no earlier
-     * stop can work, since a registered ancestor carries an own BITS of its own,
-     * and nothing above the elements declares anything.
-     *
-     * Everything deriving a component's attribute vocabulary reads it here, so
-     * the runtime and whatever documents it cannot walk the chain differently.
+     * The observed attributes are applied in the composed order, a re-declared
+     * name taking the position of its last declaration.
      * @param {*} klass a ParsedElement subclass
      * @returns {{ observed: string[], attributes: string[] }}
      */
@@ -4623,14 +4625,7 @@ class Registry {
      * The property an observed attribute drives, by the platform's own
      * dash-to-camel rule: the one `dataset` applies, so `clear-invalid-on-change`
      * would reach `clearInvalidOnChange` the way `data-clear-invalid-on-change`
-     * reaches `dataset.clearInvalidOnChange`. A single-word name is returned
-     * unchanged, which is what every observed attribute in the library is.
-     *
-     * It exists because the observed tier is the one that becomes properties:
-     * without it an attribute could only be observed if its name happened to be
-     * a usable identifier, which is why every multiword observed attribute here
-     * used to be squashed into one word while the configuration tier, which
-     * never becomes a property, spelled the same idea with a dash.
+     * reaches `dataset.clearInvalidOnChange`.
      *
      * Only this direction is mapped. A property never derives its attribute: a
      * setter reflects through `reflectTo`, naming the attribute it writes.
@@ -4643,10 +4638,6 @@ class Registry {
     #augmentAndDefineElement(tag, klass) {
         const { observed, attributes } = Registry.declarationsOf(klass);
         const { template, templates, slots, mappers, config } = klass;
-        //a name a subclass re-declares takes the subclass's position, which is
-        //how a field whose value setter reads its own shape attributes declares
-        //that its value lands after them: the order the declarations compose in
-        //is the order the base applies them
         const declaredNames = observed.map((a) => a.split(':')[0]);
         const observedNames = [...new Set(declaredNames.reverse())].reverse();
         const attrToMapper = [...attributes, ...observed].reduce((acc, a) => {
@@ -4665,20 +4656,13 @@ class Registry {
         const nameToTemplate = Object.fromEntries(namesAndTemplates);
 
         klass.BITS = {
-            //the defining registry travels with the definition: an element resolves
-            //its templates and its components through the registry that defined it,
-            //not through whichever one a module happened to import
             registry: this,
             enqueue: (el) => this.#upgradeQueue.enqueue(el),
             SLOTS: slots,
-            //the class's own constants, overlaid on its templates as `config`:
-            //read here with the rest of the declaration, so a page replacing them
-            //does it before configure() like every other definition-time choice
             CONFIG: config,
             OBSERVED: observedNames,
             DECLARED: [...new Set([...observedNames, ...attributes.map((a) => a.split(':')[0])])],
             ATTR_TO_MAPPER: attrToMapper,
-            //resolved once here rather than at every attribute write
             ATTR_TO_PROPERTY: Object.fromEntries(observedNames.map((a) => [a, Registry.propertyOf(a)])),
             TEMPLATES: nameToTemplate,
         };
@@ -4690,6 +4674,7 @@ class Registry {
      * as `#fn`.
      * @param {string} name
      * @param {object} value
+     * @returns {Registry} this registry
      */
     defineModule(name, value) {
         const module = name ? { [name]: value } : value;
@@ -4700,6 +4685,7 @@ class Registry {
     /**
      * Replaces the whole module map.
      * @param {object} ms
+     * @returns {Registry} this registry
      */
     defineModules(ms) {
         this.#modules = ms;
@@ -4711,6 +4697,7 @@ class Registry {
      * through component().
      * @param {string} name
      * @param {*} value
+     * @returns {Registry} this registry
      */
     defineComponent(name, value) {
         this.#components[name] = value;
@@ -4719,6 +4706,7 @@ class Registry {
     /**
      * Replaces the data stack the templates evaluate over.
      * @param {...any} data
+     * @returns {Registry} this registry
      */
     defineData(...data) {
         this.#data = data;
@@ -4728,6 +4716,7 @@ class Registry {
     /**
      * Appends to the data stack, the later entry winning a shared name.
      * @param {...any} data
+     * @returns {Registry} this registry
      */
     defineOverlay(...data) {
         this.#data = [...this.#data, ...data];
@@ -4739,6 +4728,7 @@ class Registry {
      * `name:type` declaration.
      * @param {string} k
      * @param {{ unmarshal(str: string|null, name: string, el: Element): any, marshal(value: any, name: string, el: Element): string|null }} v
+     * @returns {Registry} this registry
      */
     defineMapper(k, v) {
         this.#mappers[k] = v;
@@ -4747,6 +4737,7 @@ class Registry {
     /**
      * Hands the registry over to the plugin's configure.
      * @param {{ configure(registry: Registry): void }} p
+     * @returns {Registry} this registry
      */
     plugin(p) {
         p.configure(this);
@@ -4755,6 +4746,7 @@ class Registry {
     /**
      * Defines every element deferred so far; from then on, defineElement takes
      * effect immediately.
+     * @returns {Registry} this registry
      */
     configure() {
         for (const [tag, klass] of Object.entries(this.#tagToClass)) {
@@ -4766,23 +4758,36 @@ class Registry {
     }
     /**
      * Waits for the queued upgrades the filter accepts, rejecting with the first
-     * that failed: the rejecting barrier Rendering is a facade over.
+     * that failed, the upgrades enqueued meanwhile included: the rejecting
+     * barrier Rendering is a facade over.
      * @param {(el: Element) => boolean} accept
+     * @returns {Promise<void>}
      */
     settle(accept) {
         return this.#upgradeQueue.upgraded(accept);
     }
-    /** The pending upgrade of one element, undefined when it is not queued. */
+    /**
+     * The pending upgrade of one element: resolving when it has rendered,
+     * rejecting with what its upgrade threw.
+     * @param {Element} el
+     * @returns {Promise<void>|undefined} undefined when the element is not queued
+     */
     whenUpgraded(el) {
         return this.#upgradeQueue.whenUpgraded(el);
     }
-    /** The elements whose upgrade is still pending, in queue order. */
+    /**
+     * The elements whose upgrade is still pending, in queue order.
+     * @returns {Element[]}
+     */
     pending() {
         return this.#upgradeQueue.pending();
     }
     /**
-     * Waits for the page's readiness: the same moment the ftl:ready event is
-     * dispatched at, resolving immediately when that moment already passed.
+     * Waits for this registry's readiness: resolves right after its ftl:ready
+     * event is dispatched on the document, and immediately when that already
+     * happened. Never rejects: a failed upgrade counts as settled, and its
+     * rejection is left unhandled so it still reaches the console and the
+     * page's error reporting.
      * @returns {Promise<void>}
      */
     ready() {
@@ -4795,11 +4800,16 @@ class Registry {
      * The scope every template on this registry renders in: the modules and the
      * data stack, as one value. Replaced whenever either is defined, so a holder
      * of an older one keeps rendering against what it was handed.
+     * @returns {ExpressionEvaluator}
      */
     evaluator() {
         return this.#evaluator;
     }
-    /** The component registered under the name, undefined when none is. */
+    /**
+     * The component registered under the name.
+     * @param {string} name
+     * @returns {any} undefined when none is
+     */
     component(name) {
         return this.#components[name];
     }
@@ -4807,33 +4817,59 @@ class Registry {
 
 const registry = new Registry();
 
-/** The Template factories, each bound to the page registry's scope. */
 /** The Template factories bound to the page's own registry: the same four sources, with its modules and data already applied. */
 class Templates {
+    /**
+     * @param {string} html
+     * @returns {Template}
+     */
     static fromHtml(html) {
         return Template.fromHtml(html).withEvaluator(registry.evaluator());
     }
+    /**
+     * @param {string} selector for an HTMLTemplateElement
+     * @returns {Template}
+     */
     static fromSelector(selector) {
         return Template.fromSelector(selector).withEvaluator(registry.evaluator());
     }
+    /**
+     * @param {HTMLTemplateElement} templateEl consumed: its content is adopted
+     * @returns {Template}
+     */
     static fromTemplate(templateEl) {
         return Template.fromTemplate(templateEl).withEvaluator(registry.evaluator());
     }
+    /**
+     * @param {DocumentFragment} fragment
+     * @returns {Template}
+     */
     static fromFragment(fragment) {
         return Template.fromFragment(fragment).withEvaluator(registry.evaluator());
     }
 }
 
 /**
- * Awaitable rendering barriers over the registry's upgrade queue. These are
- * the rejecting waits: a failed upgrade among the awaited components rejects
- * the wait, where registry.ready() only ever means the queue drained and
- * leaves a failed component to its own unhandled-rejection report.
+ * Waits for elements queued on the page's `registry` to render. Unlike
+ * `registry.ready()`, these reject when an awaited upgrade fails. An element
+ * defined by another Registry is awaited through that registry instead.
  */
 class Rendering {
+    /**
+     * Waits for the element and its descendants, the ones their own renders
+     * enqueue included.
+     * @param {Element} el
+     * @returns {Promise<void>} rejecting with the first upgrade that failed
+     */
     static waitFor(el) {
         return registry.settle((child) => el.contains(child));
     }
+    /**
+     * Waits for the element's descendants, the element itself excluded: what a
+     * component awaits from inside its own render.
+     * @param {Element} el
+     * @returns {Promise<void>} rejecting with the first upgrade that failed
+     */
     static waitForChildren(el) {
         return registry.settle((child) => el !== child && el.contains(child));
     }
@@ -4847,9 +4883,15 @@ class Rendering {
  * @property {(val: any, name: string, el: Element) => string|null} marshal
  */
 
+/**
+ * The base of every fml element. A subclass declares its attributes, slots and
+ * templates in statics and builds its dom in `render`; the base reads the light
+ * slots, reads the declared attributes through their mappers, renders once, and
+ * then forwards observed attribute writes to the matching properties. An element
+ * resolves templates and components through the registry that defined it.
+ */
 class ParsedElement extends HTMLElement {
     static BITS = {
-        //an element the registry never defined still answers the page's own
         registry,
         enqueue: (el) => {},
         SLOTS: false,
@@ -4873,14 +4915,12 @@ class ParsedElement extends HTMLElement {
         this.internals = this.attachInternals();
     }
     /**
-     * The platform's window into the element's own state. The base attaches it
-     * for every element, so a subclass never calls attachInternals itself: the
-     * platform allows it once, and a second call throws. Form association is a
-     * property of the definition rather than of who attached, so a subclass
-     * declaring `static formAssociated` still gets the form apis here.
-     *
-     * A subclass must not redeclare it: a class field with no initializer
-     * assigns undefined after super() returns, which would wipe it.
+     * The element's ElementInternals, attached by the base for every element: a
+     * subclass never calls attachInternals itself, since a second call throws.
+     * A subclass declaring `static formAssociated` gets the form apis here.
+     * A subclass must not redeclare the field: a class field without an
+     * initializer assigns undefined after super() returns, wiping it.
+     * @type {ElementInternals}
      */
     internals;
     #parsed = false;
@@ -4897,26 +4937,36 @@ class ParsedElement extends HTMLElement {
     #mapper(attr) {
         const mapper = this.#bits().ATTR_TO_MAPPER[attr];
         if (!mapper) {
-            //an attribute the class never declared has no type to read it as:
-            //say so rather than dying on the missing mapper. Content this
-            //element does not own, such as a custom loader's own configuration,
-            //is read with getAttribute, the platform's own answer
             throw new Error(
                 `${this.constructor.name} declares no attribute '${attr}': declare it in static observed or static attributes, or read it with getAttribute`,
             );
         }
         return mapper;
     }
+    /**
+     * Reads an attribute value through the mapper it was declared with.
+     * @param {string} attr
+     * @param {string|null} str
+     * @returns {any}
+     * @throws when the class declares no such attribute; read undeclared ones with getAttribute
+     */
     unmarshal(attr, str) {
         return this.#mapper(attr).unmarshal(str, attr, this);
     }
+    /**
+     * Writes a value as the attribute string its declared mapper produces.
+     * @param {string} attr
+     * @param {any} value
+     * @returns {string|null} null for a value that removes the attribute
+     * @throws when the class declares no such attribute
+     */
     marshal(attr, value) {
         return this.#mapper(attr).marshal(value, attr, this);
     }
     /**
-     * @param {string} [name] - The name of the template target, defaults to 'default'
+     * The registry that defined this element, the page's own for an undefined one.
+     * @returns {typeof registry}
      */
-    /** The registry that defined this element, the page's own for an undefined one. */
     get _registry() {
         return this.#bits().registry;
     }
@@ -4924,10 +4974,18 @@ class ParsedElement extends HTMLElement {
      * The component registered under the name on this element's registry, the
      * one every ful loader and mapper resolves through.
      * @param {string} name
+     * @returns {any} undefined when none is registered
      */
     component(name) {
         return this.#bits().registry.component(name);
     }
+    /**
+     * One of the class's templates, bound to its registry's scope with the
+     * class's `static config` overlaid as `config`.
+     * @param {string} [name] 'default', the `static template`, when omitted
+     * @returns {Template}
+     * @throws when the class declares no template of that name
+     */
     template(name) {
         const target = this.#bits().TEMPLATES[name ?? 'default'];
         if (!target) {
@@ -4947,15 +5005,9 @@ class ParsedElement extends HTMLElement {
         if (oldValue === newValue) {
             return;
         }
-        //the mute is the attribute being reflected, not the element: a component
-        //that legitimately changes another observed attribute while one reflects
-        //is a change like any other, and used to be swallowed
         if (this.#reflecting.has(attr)) {
             return;
         }
-        //the properties go live only once the render is done: before that, an
-        //attribute write lands in the observed snapshot and the base applies it
-        //with the rest of the declared state
         if (!this.#parsed) {
             if (this.#pending !== null && attr in this.#pending) {
                 this.#pending[attr] = this.unmarshal(attr, newValue);
@@ -4965,14 +5017,18 @@ class ParsedElement extends HTMLElement {
         this[this.#bits().ATTR_TO_PROPERTY[attr]] = this.unmarshal(attr, newValue);
     }
     /**
-     * Upgrades once: reads the declared attributes, keeps the observed half open
-     * to writes made while the render is pending, applies them to the properties
-     * when the render returns, and only then lets an attribute write forward.
+     * Upgrades once, however often the element is connected: reads the declared
+     * attributes, keeps the observed ones open to writes made while the render is
+     * pending, renders, then applies the observed values to their properties in
+     * the order the registry composed them, a base class's before a subclass's.
+     * Only then do attribute writes forward to properties, and the element gains
+     * the `rendered` custom state. A render that throws leaves the forwarding
+     * shut and the state unset.
      *
      * An observed attribute drives the property the registry's `propertyOf`
      * names, so a hyphenated attribute is authored with its dashes and read as
-     * a camelCase property. A single-word attribute is its own property name,
-     * which is what every observed attribute in the library is.
+     * a camelCase property.
+     * @returns {Promise<void>} rejecting with what the render threw
      */
     async upgrade() {
         if (this.#started) {
@@ -4980,9 +5036,6 @@ class ParsedElement extends HTMLElement {
         }
         this.#started = true;
         const slots = this.#bits().SLOTS ? LightSlots.from(this) : undefined;
-        //both tiers are read here: the observed ones forward to a property once
-        //the render is done, the rest are the element's configuration, read the
-        //one time and never again
         const declared = Object.fromEntries(
             this.#bits().DECLARED.map((attribute) => [
                 attribute,
@@ -4994,21 +5047,11 @@ class ParsedElement extends HTMLElement {
         this.#pending = declared;
         try {
             await this.render({ slots });
-            //the declared state reaches the properties once the dom the setters
-            //drive exists, in the order the registry composed the declarations:
-            //a base class's attributes before the subclass's own
             const properties = this.#bits().ATTR_TO_PROPERTY;
             for (const name of this.#bits().OBSERVED) {
                 this[properties[name]] = declared[name];
             }
-            //the properties go live once the render is done: from here on, an
-            //attribute write forwards to the property. A render that threw
-            //leaves it shut, so a later attribute write cannot reach setters
-            //that assume pieces the failed render never adopted
             this.#parsed = true;
-            //the same moment, said to css. :defined is true from the constructor,
-            //which is before the dom exists, so a guard written against it reveals
-            //an element that has nothing in it yet
             this.internals.states.add('rendered');
         } finally {
             this.#pending = null;
@@ -5019,8 +5062,9 @@ class ParsedElement extends HTMLElement {
      * drive, and the base applies the declared state onto the properties as
      * soon as it returns. A render needing a declared value while it builds
      * reads it through `declared(name)`. The slots are undefined for an element
-     * declaring no slots.
-     * @param {{ slots: any }} c
+     * declaring no slots. It may be async; the upgrade awaits it.
+     * @param {{ slots: Record<string, DocumentFragment> | undefined }} c
+     * @returns {void | Promise<void>}
      */
     render(c) {}
     /**
@@ -5032,12 +5076,9 @@ class ParsedElement extends HTMLElement {
      * observed name answers the snapshot while the render is pending, kept
      * open to attribute writes landing in that window, and the live attribute
      * afterwards, the property being live by then.
-     *
-     * The snapshot exists rather than a read of the dom because an element may
-     * write its own observed attributes while it renders, whether a reflection
-     * or a value the platform normalizes on the way in, and what the author
-     * declared is what the base applies, not what the render left behind.
      * @param {string} name
+     * @returns {any}
+     * @throws when the class declares no such attribute
      */
     declared(name) {
         if (name in this.#frozen) {
@@ -5048,15 +5089,18 @@ class ParsedElement extends HTMLElement {
         }
         return this.unmarshal(name, this.getAttribute(name));
     }
-    /** Whether the element's render completed: the moment its properties went live. */
+    /**
+     * Whether the element's render completed: the moment its properties went
+     * live, which css reads as `:state(rendered)`. Unlike `:defined`, which holds
+     * from the constructor, it is false until the dom exists.
+     * @returns {boolean}
+     */
     get rendered() {
         return this.#parsed;
     }
     /**
      * Projects a property back onto its observed attribute, marshalled through
-     * the mapper the attribute was declared with: the one place a property
-     * reaches its attribute, so a setter never has to know how its own type
-     * serializes.
+     * the mapper the attribute was declared with.
      *
      * A value the attribute already carries is not written at all, so reflecting
      * what an attribute write just delivered ends there rather than looping, and
@@ -5098,7 +5142,10 @@ const POSITIONAL = /\{(\d+)\}/g;
 /** @param {any} v @returns {v is Record<string, string>} */
 const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 
-/** every l10n problem is reported once per session: a missing key in a row template must not flood the console */
+/** @param {any} problem @returns {string|undefined} the reason, unless it is missing or blank */
+const reasonOf = (problem) =>
+    typeof problem?.reason === 'string' && problem.reason.trim() !== '' ? problem.reason : undefined;
+
 const warned = new Set();
 const warnOnce = (problem) => {
     if (!warned.has(problem)) {
@@ -5109,11 +5156,7 @@ const warnOnce = (problem) => {
 
 const formatters = new BoundedCache(100);
 /**
- * Intl construction is the expensive part of formatting (locale parsing, CLDR
- * lookups), while formatting on a built instance is near free: a list rendering
- * a size per row must not rebuild a NumberFormat per cell, so instances are
- * memoized by constructor, locale and options.
- *
+ * An Intl instance, memoized by constructor, locale and options.
  * @param {{ new (locale: string | undefined, options: any): any }} ctor
  * @param {string | undefined} locale
  * @param {any} [options]
@@ -5139,6 +5182,9 @@ class Localization {
      *
      * @param {string} key
      * @param {...any} args
+     * Each problem (a missing key, placeholder or plural form) is warned once
+     * per page.
+     *
      * @this {Receiver}
      * @returns {string} the message, or the key itself when the translations do not carry it
      */
@@ -5149,9 +5195,9 @@ class Localization {
             warnOnce(`missing message "${key}"`);
             return key;
         }
+        const named = args.length === 1 && isPlainObject(args[0]) ? args[0] : null;
         if (isPlainObject(message)) {
-            const named = args.length === 1 && isPlainObject(args[0]) ? args[0] : {};
-            if (typeof named.count !== 'number') {
+            if (typeof named?.count !== 'number') {
                 warnOnce(`plural message "${key}" needs a numeric {count}`);
                 message = message.other;
             } else {
@@ -5164,8 +5210,7 @@ class Localization {
             warnOnce(`plural message "${key}" has no "other" form`);
             return key;
         }
-        if (args.length === 1 && isPlainObject(args[0])) {
-            const named = args[0];
+        if (named) {
             return message.replace(PLACEHOLDER, (literal, name) => {
                 if (!Object.hasOwn(named, name)) {
                     warnOnce(`message "${key}" wants {${name}}`);
@@ -5193,6 +5238,7 @@ class Localization {
      * @param {Date | number} value
      * @param {Intl.DateTimeFormatOptions} [options]
      * @this {Receiver}
+     * @returns {string}
      */
     static date(value, options) {
         return formatter(Intl.DateTimeFormat, this.locale, options).format(value);
@@ -5204,6 +5250,7 @@ class Localization {
      * @param {number} value
      * @param {Intl.NumberFormatOptions} [options]
      * @this {Receiver}
+     * @returns {string}
      */
     static number(value, options) {
         return formatter(Intl.NumberFormat, this.locale, options).format(value);
@@ -5216,6 +5263,7 @@ class Localization {
      *
      * @param {number} value
      * @this {Receiver}
+     * @returns {string}
      */
     static bytes(value) {
         const format = formatter(Intl.NumberFormat, this.locale, { maximumFractionDigits: 2 }).format;
@@ -5231,16 +5279,37 @@ class Localization {
         return `${format(value)}B`;
     }
 
+    /**
+     * What went wrong, as text for the reader. A value carrying a non-empty
+     * `problems` array reads as their reasons, one per line, a blank or missing
+     * reason reading as the `failure.no-reason` message. Any other value with a
+     * `message` reads as that message; anything else as its string form, and
+     * null or undefined as the empty string.
+     *
+     * @param {any} value what was thrown or rejected with
+     * @this {Receiver}
+     * @returns {string}
+     */
+    static failure(value) {
+        if (Array.isArray(value?.problems) && value.problems.length > 0) {
+            return value.problems.map((p) => reasonOf(p) ?? Localization.t.call(this, 'failure.no-reason')).join('\n');
+        }
+        if (value?.message !== undefined) {
+            return String(value.message);
+        }
+        return value == null ? '' : String(value);
+    }
+
     /**
      * An imperative facade over the module functions, resolving the translations
-     * and the locale from the registry overlays on every call.
+     * and the locale from the registry overlays on every call, the same lookup a
+     * template makes: a facade taken at module scope, before the plugin
+     * configures, still sees the translations.
      *
      * @param {{ locale?: string }} [overrides] an explicit locale, winning over the registry one
+     * @returns {{ t: (key: string, ...args: any[]) => string, date: (value: Date | number, options?: Intl.DateTimeFormatOptions) => string, number: (value: number, options?: Intl.NumberFormatOptions) => string, bytes: (value: number) => string, failure: (value: any) => string }}
      */
     static of(overrides = {}) {
-        //resolved per call, not per facade: a module-scope `Localization.of()` is
-        //bound before the plugin configures. The registry's own evaluator does the
-        //lookup, so this cannot drift from what a template sees
         const resolve = (prop) => registry.evaluator().resolve(prop);
         /** @param {any} fn */
         const bind =
@@ -5252,6 +5321,7 @@ class Localization {
             date: bind(Localization.date),
             number: bind(Localization.number),
             bytes: bind(Localization.bytes),
+            failure: bind(Localization.failure),
         };
     }
 }