@optionfactory/fml 9.0.0-rc15 → 9.0.0-rc18

package/dist/ftl.iife.js

@@ -2,12 +2,8 @@ var ftl = (function (exports) {
     'use strict';
 
     /**
-     * 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;
@@ -36,6 +32,7 @@ var ftl = (function (exports) {
             this.#entries.set(key, value);
             return value;
         }
+        /** @returns {number} the number of entries held */
         get size() {
             return this.#entries.size;
         }
@@ -78,10 +75,6 @@ var ftl = (function (exports) {
     //
     // 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],
@@ -3253,10 +3246,10 @@ var ftl = (function (exports) {
     /**
      * 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') {
@@ -3320,8 +3313,7 @@ var ftl = (function (exports) {
             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);
@@ -3388,8 +3380,7 @@ var ftl = (function (exports) {
             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;
@@ -3455,16 +3446,23 @@ var ftl = (function (exports) {
      * 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;
@@ -3475,12 +3473,12 @@ var ftl = (function (exports) {
             );
         }
         /**
-         * 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);
@@ -3488,10 +3486,10 @@ var ftl = (function (exports) {
         /**
          * 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);
@@ -3507,14 +3505,31 @@ var ftl = (function (exports) {
     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,
@@ -3525,26 +3540,36 @@ var ftl = (function (exports) {
          * 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');
@@ -3552,11 +3577,11 @@ var ftl = (function (exports) {
             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');
@@ -3564,17 +3589,17 @@ var ftl = (function (exports) {
             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();
@@ -3584,9 +3609,10 @@ var ftl = (function (exports) {
             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();
@@ -3597,23 +3623,23 @@ var ftl = (function (exports) {
         }
     }
 
-    /** 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)) {
@@ -3622,7 +3648,9 @@ var ftl = (function (exports) {
             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
@@ -3645,7 +3673,7 @@ var ftl = (function (exports) {
                 });
         }
         /**
-         * 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
@@ -3667,13 +3695,14 @@ var ftl = (function (exports) {
      */
     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');
@@ -3699,6 +3728,12 @@ var ftl = (function (exports) {
             }
             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);
@@ -3710,12 +3745,13 @@ var ftl = (function (exports) {
         }
     }
 
-    /** 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) {
@@ -3727,13 +3763,12 @@ var ftl = (function (exports) {
         }
 
         /**
-         * 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') {
@@ -3746,7 +3781,6 @@ var ftl = (function (exports) {
             }
             const win = doc.defaultView;
             if (win === null) {
-                //a viewless document can receive no event at all
                 return Promise.resolve();
             }
             return new Promise((resolve) => {
@@ -3766,18 +3800,8 @@ var ftl = (function (exports) {
          * 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)) {
@@ -3802,10 +3826,10 @@ var ftl = (function (exports) {
         }
 
         /**
-         * 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) {
@@ -3816,10 +3840,10 @@ var ftl = (function (exports) {
             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 = [];
@@ -3876,9 +3900,11 @@ var ftl = (function (exports) {
 
     /** 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',
@@ -3889,8 +3915,7 @@ var ftl = (function (exports) {
             '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) {
@@ -3905,49 +3930,36 @@ var ftl = (function (exports) {
                 .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,
@@ -3957,16 +3969,13 @@ var ftl = (function (exports) {
                     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) {
@@ -3980,12 +3989,8 @@ var ftl = (function (exports) {
         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 {
@@ -4048,12 +4053,10 @@ var ftl = (function (exports) {
         }
     }
 
-    // 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}
      */
@@ -4075,38 +4078,40 @@ var ftl = (function (exports) {
      */
     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);
@@ -4114,11 +4119,12 @@ var ftl = (function (exports) {
         }
 
         /**
-         * 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));
@@ -4138,28 +4144,32 @@ var ftl = (function (exports) {
          * 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));
@@ -4168,7 +4178,7 @@ var ftl = (function (exports) {
          * 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);
@@ -4177,33 +4187,29 @@ var ftl = (function (exports) {
          * 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,
@@ -4229,8 +4235,6 @@ var ftl = (function (exports) {
                         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)) {
@@ -4253,17 +4257,13 @@ var ftl = (function (exports) {
                                 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;
                 }
@@ -4271,22 +4271,26 @@ var ftl = (function (exports) {
             }
         }
         /**
-         * 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);
@@ -4295,8 +4299,10 @@ var ftl = (function (exports) {
             }
         }
         /**
-         * 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);
@@ -4320,30 +4326,26 @@ var ftl = (function (exports) {
     }
 
     /**
-     * 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) {
@@ -4352,27 +4354,44 @@ var ftl = (function (exports) {
             }
             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) {
@@ -4391,10 +4410,13 @@ var ftl = (function (exports) {
         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) {
@@ -4416,11 +4438,6 @@ var ftl = (function (exports) {
         }
     }
 
-    /**
-     * 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;
@@ -4432,12 +4449,6 @@ var ftl = (function (exports) {
                 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;
         }
@@ -4453,13 +4464,8 @@ var ftl = (function (exports) {
         }
         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()
             );
@@ -4471,11 +4477,6 @@ var ftl = (function (exports) {
                 });
             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)
@@ -4488,22 +4489,25 @@ var ftl = (function (exports) {
             }
         }
         /**
-         * 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());
         }
@@ -4514,8 +4518,8 @@ var ftl = (function (exports) {
      * 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 = {};
@@ -4584,9 +4588,12 @@ var ftl = (function (exports) {
          * 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) {
@@ -4604,13 +4611,8 @@ var ftl = (function (exports) {
          * 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[] }}
          */
@@ -4626,14 +4628,7 @@ var ftl = (function (exports) {
          * 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.
@@ -4646,10 +4641,6 @@ var ftl = (function (exports) {
         #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) => {
@@ -4668,20 +4659,13 @@ var ftl = (function (exports) {
             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,
             };
@@ -4693,6 +4677,7 @@ var ftl = (function (exports) {
          * as `#fn`.
          * @param {string} name
          * @param {object} value
+         * @returns {Registry} this registry
          */
         defineModule(name, value) {
             const module = name ? { [name]: value } : value;
@@ -4703,6 +4688,7 @@ var ftl = (function (exports) {
         /**
          * Replaces the whole module map.
          * @param {object} ms
+         * @returns {Registry} this registry
          */
         defineModules(ms) {
             this.#modules = ms;
@@ -4714,6 +4700,7 @@ var ftl = (function (exports) {
          * through component().
          * @param {string} name
          * @param {*} value
+         * @returns {Registry} this registry
          */
         defineComponent(name, value) {
             this.#components[name] = value;
@@ -4722,6 +4709,7 @@ var ftl = (function (exports) {
         /**
          * Replaces the data stack the templates evaluate over.
          * @param {...any} data
+         * @returns {Registry} this registry
          */
         defineData(...data) {
             this.#data = data;
@@ -4731,6 +4719,7 @@ var ftl = (function (exports) {
         /**
          * 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];
@@ -4742,6 +4731,7 @@ var ftl = (function (exports) {
          * `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;
@@ -4750,6 +4740,7 @@ var ftl = (function (exports) {
         /**
          * Hands the registry over to the plugin's configure.
          * @param {{ configure(registry: Registry): void }} p
+         * @returns {Registry} this registry
          */
         plugin(p) {
             p.configure(this);
@@ -4758,6 +4749,7 @@ var ftl = (function (exports) {
         /**
          * 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)) {
@@ -4769,23 +4761,36 @@ var ftl = (function (exports) {
         }
         /**
          * 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() {
@@ -4798,11 +4803,16 @@ var ftl = (function (exports) {
          * 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];
         }
@@ -4810,33 +4820,59 @@ var ftl = (function (exports) {
 
     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));
         }
@@ -4850,9 +4886,15 @@ var ftl = (function (exports) {
      * @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,
@@ -4876,14 +4918,12 @@ var ftl = (function (exports) {
             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;
@@ -4900,26 +4940,36 @@ var ftl = (function (exports) {
         #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;
         }
@@ -4927,10 +4977,18 @@ var ftl = (function (exports) {
          * 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) {
@@ -4950,15 +5008,9 @@ var ftl = (function (exports) {
             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);
@@ -4968,14 +5020,18 @@ var ftl = (function (exports) {
             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) {
@@ -4983,9 +5039,6 @@ var ftl = (function (exports) {
             }
             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,
@@ -4997,21 +5050,11 @@ var ftl = (function (exports) {
             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;
@@ -5022,8 +5065,9 @@ var ftl = (function (exports) {
          * 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) {}
         /**
@@ -5035,12 +5079,9 @@ var ftl = (function (exports) {
          * 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) {
@@ -5051,15 +5092,18 @@ var ftl = (function (exports) {
             }
             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
@@ -5101,7 +5145,10 @@ var ftl = (function (exports) {
     /** @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)) {
@@ -5112,11 +5159,7 @@ var ftl = (function (exports) {
 
     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]
@@ -5142,6 +5185,9 @@ var ftl = (function (exports) {
          *
          * @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
          */
@@ -5152,9 +5198,9 @@ var ftl = (function (exports) {
                 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 {
@@ -5167,8 +5213,7 @@ var ftl = (function (exports) {
                 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}}`);
@@ -5196,6 +5241,7 @@ var ftl = (function (exports) {
          * @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);
@@ -5207,6 +5253,7 @@ var ftl = (function (exports) {
          * @param {number} value
          * @param {Intl.NumberFormatOptions} [options]
          * @this {Receiver}
+         * @returns {string}
          */
         static number(value, options) {
             return formatter(Intl.NumberFormat, this.locale, options).format(value);
@@ -5219,6 +5266,7 @@ var ftl = (function (exports) {
          *
          * @param {number} value
          * @this {Receiver}
+         * @returns {string}
          */
         static bytes(value) {
             const format = formatter(Intl.NumberFormat, this.locale, { maximumFractionDigits: 2 }).format;
@@ -5234,16 +5282,37 @@ var ftl = (function (exports) {
             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 =
@@ -5255,6 +5324,7 @@ var ftl = (function (exports) {
                 date: bind(Localization.date),
                 number: bind(Localization.number),
                 bytes: bind(Localization.bytes),
+                failure: bind(Localization.failure),
             };
         }
     }