@optionfactory/fml 9.0.0-rc3 → 9.0.0-rc31

package/dist/ftl.d.mts

@@ -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.
  */
 declare class BoundedCache {
     #private;
@@ -20,6 +16,7 @@ declare class BoundedCache {
      * @returns {V}
      */
     getOrCompute<K, V>(key: K, compute: (key: K) => V): V;
+    /** @returns {number} the number of entries held */
     get size(): number;
 }
 /**
@@ -31,121 +28,180 @@ declare class BoundedCache {
  */
 declare class Expressions {
     #private;
+    /** Parses the whole text as one expression: `user.name`. */
     static MODE_EXPRESSION: symbol;
+    /**
+     * 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;
     /**
-     * Parses an expression.
+     * The key under which the receiver of a module function answers a lookup
+     * against the bound data alone: `this[Expressions.BOUND](name)` resolves
+     * the name in the layers the scope was created with (a registry's data,
+     * the data handed to a Template factory) and never in an overlay pushed
+     * afterwards, by `data-tpl-each`, `data-tpl-with` or `withOverlay`. It is
+     * how a module reads what the page configured without the rendered data
+     * being able to supply or replace it. No name on the data stack reaches it.
+     */
+    static BOUND: symbol;
+    /**
+     * 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: string, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null): any;
     /**
-     * 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
+     * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
+     * @returns {any} the value, or the list of parts in MODE_TEMPLATED
      */
     static evaluate(modules: {
         [k: string]: any;
-    } | null | undefined, dataStack: any[], ast: any, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null): any;
+    } | null | undefined, dataStack: any[], ast: any, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null, bound?: number): any;
     /**
      * 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
+     * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
+     * @returns {any} the value, or the list of parts in MODE_TEMPLATED
      */
     static interpret(modules: {
         [x: string]: any;
-    } | null | undefined, dataStack: any[], expression: string, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null): any;
+    } | null | undefined, dataStack: any[], expression: string, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null, bound?: number): any;
 }
 /**
  * A scope: the modules that `#name:fn()` resolves against and the data stack
  * that a bare identifier resolves against, as a single value. Adding an overlay
  * returns a new evaluator instead of modifying this one, so a template can add
  * data for one subtree without affecting the rest of the render.
+ *
+ * The layers an evaluator is created with are its bound data; the overlays
+ * pushed afterwards are not. A bare identifier resolves against both, while a
+ * module function can ask for the bound data alone through `Expressions.BOUND`.
  */
 declare class ExpressionEvaluator {
     #private;
-    constructor(modules: any, dataStack: any);
-    withModule(name: any, value: any): ExpressionEvaluator;
+    /**
+     * @param {{ [k: string]: any } | null | undefined} modules
+     * @param {any[]} dataStack innermost overlay last
+     * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
+     */
+    constructor(modules: {
+        [k: string]: any;
+    } | null | undefined, dataStack: any[], bound?: number);
+    /**
+     * 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: string, value: object): ExpressionEvaluator;
+    /**
+     * A new evaluator with the data pushed as the innermost overlays, the last
+     * one winning a shared name. The bound data stays what it was.
+     * @param {...any} data
+     * @returns {ExpressionEvaluator}
+     */
     withOverlay(...data: any[]): 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: string): any;
-    /** Evaluates an expression against this scope. */
-    evaluateExpression(expression: any): any;
-    /** Evaluates a templated text, the `{{ }}` form, against this scope. */
-    evaluateTemplated(text: any): any;
+    /**
+     * Evaluates an expression against this scope.
+     * @param {string} expression
+     * @returns {any}
+     */
+    evaluateExpression(expression: string): any;
+    /**
+     * 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: string): {
+        type: symbol;
+        value: any;
+    }[];
 }
-/** Creates and inspects the DocumentFragments a Template renders into. */
+/** Creates, serializes and inspects DocumentFragments. */
 declare 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: string[]): DocumentFragment;
     /**
-     * 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: DocumentFragment): string;
+    static toHtml(fragment: DocumentFragment | Node): string;
     /**
-     * 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: DocumentFragment): boolean;
     /**
-     * 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: Node[]): DocumentFragment;
     /**
-     * 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: Node): DocumentFragment;
 }
-/** 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. */
 declare class Attributes {
     static id: number;
     /**
-     * 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: string): string;
     /**
-     * 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: Element, k: string, v: string): string | null;
     /**
-     * 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
      */
     static forward(prefix: string, from: Element, to: Element): void;
     /**
-     * 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
@@ -160,67 +216,64 @@ declare class Attributes {
  */
 declare 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: Element): {
-        default: DocumentFragment;
-    };
-    static slotFromNode(el: any): any;
+    static from(el: Element): Record<string, DocumentFragment>;
+    /**
+     * 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: Element): Element | DocumentFragment;
 }
-/** 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. */
 declare 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: Element): boolean;
     /**
-     * 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: any): Promise<any>;
+    static waitDomContentLoaded(doc: Document): Promise<void>;
     /**
      * Waits for the element's closing tag to be parsed: one MutationObserver
      * resolves once the element, or any of its ancestors, gains a next sibling,
      * 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>}
-     */
-    static waitParsed(el: any): Promise<any>;
-    /**
-     * Returns the first child of the element element (if exists) matching the selector.
+     * that is already parsed, or once the parser has finished the document.
      * @param {Element} el
+     * @returns {Promise<Element>} the element
+     */
+    static waitParsed(el: Element): Promise<Element>;
+    /**
+     * The first child element matching the selector, descendants excluded.
+     * @param {Element|DocumentFragment} el
      * @param {string} selector
-     * @returns
+     * @returns {Element|null}
      */
-    static queryChildren(el: Element, selector: string): Element | null;
+    static queryChildren(el: Element | DocumentFragment, selector: string): Element | 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: Element, selector: string): Element[];
+    static queryChildrenAll(el: Element | DocumentFragment, selector: string): Element[];
 }
 /**
  * A compiled fragment together with the scope it renders in. Both are
@@ -231,41 +284,45 @@ declare class Nodes {
 declare class Template {
     #private;
     /**
-     * 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: string, modules?: {
         [k: string]: any;
     } | null, ...data: any[]): Template;
     /**
-     * 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: string, modules?: {
         [k: string]: any;
     } | null, ...data: any[]): Template;
     /**
-     * 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: HTMLTemplateElement, modules?: {
         [k: string]: any;
     } | null, ...data: any[]): 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: DocumentFragment, modules?: {
         [k: string]: any;
@@ -280,117 +337,151 @@ declare 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: ExpressionEvaluator): Template;
     /**
-     * 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: DocumentFragment): Template;
     /**
-     * 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: string | null, value: {
         [k: string]: any;
     }): Template;
     /**
-     * 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: any[]): 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: string, ...data: any[]): any;
     /**
      * 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: string, ...data: any[]): any;
+    evaluateTemplated(text: string, ...data: any[]): {
+        type: symbol;
+        value: any;
+    }[];
     /**
-     * Returns an expression evaluator with bound modules and dataStack.
+     * The scope this template renders in.
+     * @returns {ExpressionEvaluator}
      */
     evaluator(): ExpressionEvaluator;
     /**
-     * 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(): DocumentFragment;
     /**
-     * Renders this template on the Element (replacing children).
+     * Renders this template into the element, replacing its children.
      * @param {Element} el
+     * @throws {RenderError}
      */
     renderTo(el: Element): void;
     /**
-     * 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: Element): void;
     /**
-     * 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: string): void;
     /**
-     * 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: string): void;
 }
 /**
- * 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.
  */
 declare class RenderError extends Error {
     #private;
-    /**
-     * 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: number;
-    /** true when the budget dropped the outer frames of this chain */
+    /** Whether the chain dropped outer frames to stay within FRAMES. */
     truncated: boolean;
     /**
-     * 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.
-     */
-    static wrap(message: any, nodeOrFragment: any, cause: any): RenderError;
-    constructor(message: any, nodeOrFragment: any, cause: any);
-    /** How many frames this chain carries, this one included. */
-    get depth(): any;
-    /** The node the render failed on, live: it keeps its place in the fragment being built. */
-    get node(): any;
-    /** The node's markup, serialized when asked for rather than on every failure. */
+     * 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: string, nodeOrFragment: Node, cause: any): RenderError;
+    /**
+     * @param {string} message
+     * @param {Node} nodeOrFragment the node that failed
+     * @param {any} cause
+     */
+    constructor(message: string, nodeOrFragment: Node, cause: any);
+    /**
+     * How many frames this chain carries, this one included.
+     * @returns {number}
+     */
+    get depth(): number;
+    /**
+     * The node the render failed on, live in the fragment being built.
+     * @returns {Node}
+     */
+    get node(): Node;
+    /**
+     * The failed node's markup, whitespace trimmed, serialized on each read.
+     * @returns {string}
+     */
     get html(): string;
     /**
      * 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: Node): string;
+    /**
+     * 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 describe(nodeOrFragment: any): any;
-    static stringify(nodeOrFragment: any): string;
+    static stringify(nodeOrFragment: Node): string;
 }
 /**
  * The page's single source of truth for elements, modules, data, components
  * 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.
  */
 declare class Registry {
     #private;
@@ -398,11 +489,14 @@ declare 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: string, klass: any): this;
+    defineElement(tag: string, klass: any): Registry;
     /**
      * The attribute declarations a class composes along its inheritance chain,
      * base first: `observed` stay live after the upgrade and drive the property
@@ -411,13 +505,8 @@ declare 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[] }}
      */
@@ -429,14 +518,7 @@ declare 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.
@@ -450,65 +532,90 @@ declare class Registry {
      * as `#fn`.
      * @param {string} name
      * @param {object} value
+     * @returns {Registry} this registry
      */
-    defineModule(name: string, value: object): this;
+    defineModule(name: string, value: object): Registry;
     /**
      * Replaces the whole module map.
      * @param {object} ms
+     * @returns {Registry} this registry
      */
-    defineModules(ms: object): this;
+    defineModules(ms: object): Registry;
     /**
      * Registers a named component (a loader, a response mapper), fetched back
      * through component().
      * @param {string} name
      * @param {*} value
+     * @returns {Registry} this registry
      */
-    defineComponent(name: string, value: any): this;
+    defineComponent(name: string, value: any): Registry;
     /**
      * Replaces the data stack the templates evaluate over.
      * @param {...any} data
+     * @returns {Registry} this registry
      */
-    defineData(...data: any[]): this;
+    defineData(...data: any[]): Registry;
     /**
      * Appends to the data stack, the later entry winning a shared name.
      * @param {...any} data
+     * @returns {Registry} this registry
      */
-    defineOverlay(...data: any[]): this;
+    defineOverlay(...data: any[]): Registry;
     /**
      * Registers a custom attribute mapper type, available to every later
      * `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: string, v: {
         unmarshal(str: string | null, name: string, el: Element): any;
         marshal(value: any, name: string, el: Element): string | null;
-    }): this;
+    }): Registry;
     /**
      * Hands the registry over to the plugin's configure.
      * @param {{ configure(registry: Registry): void }} p
+     * @returns {Registry} this registry
      */
     plugin(p: {
         configure(registry: Registry): void;
-    }): this;
+    }): Registry;
     /**
      * Defines every element deferred so far; from then on, defineElement takes
-     * effect immediately.
+     * effect immediately. Readiness waits for the first call: a page that
+     * configures late (translations fetched first) gets its ftl:ready once the
+     * elements this defines have upgraded, not at DOMContentLoaded.
+     * @returns {Registry} this registry
      */
-    configure(): this;
+    configure(): 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: (el: Element) => boolean): Promise<void>;
-    /** The pending upgrade of one element, undefined when it is not queued. */
-    whenUpgraded(el: any): any;
-    /** The elements whose upgrade is still pending, in queue order. */
-    pending(): any[];
     /**
-     * Waits for the page's readiness: the same moment the ftl:ready event is
-     * dispatched at, resolving immediately when that moment already passed.
+     * 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: Element): Promise<void> | undefined;
+    /**
+     * The elements whose upgrade is still pending, in queue order.
+     * @returns {Element[]}
+     */
+    pending(): Element[];
+    /**
+     * Waits for this registry's readiness: resolves right after its ftl:ready
+     * event is dispatched on the document, and immediately when that already
+     * happened. The event is dispatched once DOMContentLoaded has passed,
+     * configure() has been called and the queue has drained, so a registry
+     * that is never configured is never ready. 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(): Promise<void>;
@@ -516,29 +623,60 @@ declare 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(): ExpressionEvaluator;
-    /** The component registered under the name, undefined when none is. */
-    component(name: any): any;
+    /**
+     * The component registered under the name.
+     * @param {string} name
+     * @returns {any} undefined when none is
+     */
+    component(name: string): any;
 }
 declare const registry: 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. */
 declare class Templates {
-    static fromHtml(html: any): Template;
-    static fromSelector(selector: any): Template;
-    static fromTemplate(templateEl: any): Template;
-    static fromFragment(fragment: any): Template;
+    /**
+     * @param {string} html
+     * @returns {Template}
+     */
+    static fromHtml(html: string): Template;
+    /**
+     * @param {string} selector for an HTMLTemplateElement
+     * @returns {Template}
+     */
+    static fromSelector(selector: string): Template;
+    /**
+     * @param {HTMLTemplateElement} templateEl consumed: its content is adopted
+     * @returns {Template}
+     */
+    static fromTemplate(templateEl: HTMLTemplateElement): Template;
+    /**
+     * @param {DocumentFragment} fragment
+     * @returns {Template}
+     */
+    static fromFragment(fragment: DocumentFragment): Template;
 }
 /**
- * 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.
  */
 declare class Rendering {
-    static waitFor(el: any): Promise<void>;
-    static waitForChildren(el: any): Promise<void>;
+    /**
+     * 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: Element): Promise<void>;
+    /**
+     * 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: Element): Promise<void>;
 }
 export type Mapper = {
     unmarshal: (val: string | null | undefined, name: string, el: Element) => any;
@@ -551,6 +689,13 @@ export type Mapper = {
  * @property {(val: string|null|undefined, name: string, el: Element) => any} unmarshal
  * @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.
+ */
 declare class ParsedElement extends HTMLElement {
     #private;
     static BITS: {
@@ -572,41 +717,65 @@ declare class ParsedElement extends HTMLElement {
     static get observedAttributes(): string[];
     constructor();
     /**
-     * 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: ElementInternals;
-    unmarshal(attr: any, str: any): any;
-    marshal(attr: any, value: any): string | null;
     /**
-     * @param {string} [name] - The name of the template target, defaults to 'default'
+     * 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
      */
-    /** The registry that defined this element, the page's own for an undefined one. */
-    get _registry(): Registry;
+    unmarshal(attr: string, str: string | null): any;
+    /**
+     * 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: string, value: any): string | null;
+    /**
+     * The registry that defined this element, the page's own for an undefined one.
+     * @returns {typeof registry}
+     */
+    get _registry(): typeof registry;
     /**
      * 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: string): any;
-    template(name: any): any;
+    /**
+     * 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?: string): Template;
     connectedCallback(): void;
     attributeChangedCallback(attr: any, oldValue: any, newValue: any): void;
     /**
-     * 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
      */
     upgrade(): Promise<void>;
     /**
@@ -614,12 +783,13 @@ declare 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: {
-        slots: any;
-    }): void;
+        slots: Record<string, DocumentFragment> | undefined;
+    }): void | Promise<void>;
     /**
      * The declared value of an attribute, unmarshalled through its mapper.
      *
@@ -629,21 +799,21 @@ declare 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: string): any;
-    /** 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(): boolean;
     /**
      * 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
@@ -662,18 +832,23 @@ export type Receiver = {
  * The translations as a template module: `#l10n:t()` for messages, plus date,
  * number and bytes formatting in the page's locale. The template form and the
  * imperative `of()` facade both resolve through the registry's scope, so they
- * always produce the same result for the same key.
+ * always produce the same result for the same key. A template reads `l10n`
+ * and `locale` from its bound data only, the most recent layer winning: an
+ * overlay pushed while rendering (a row, a response) never reaches them.
  */
 declare class Localization {
     /**
      * Resolves a message from the translations and interpolates its arguments.
-     * A single plain object argument interpolates named placeholders
-     * ({name}); anything else interpolates positional ones ({0}).
+     * A single plain object argument (an object literal, or one with a null
+     * prototype) interpolates named placeholders ({name}); anything else interpolates positional ones ({0}).
      * A plural leaf selects its form through Intl.PluralRules over the
      * numeric {count} named argument.
      *
      * @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
      */
@@ -684,16 +859,18 @@ declare class Localization {
      * @param {Date | number} value
      * @param {Intl.DateTimeFormatOptions} [options]
      * @this {Receiver}
+     * @returns {string}
      */
-    static date(this: Receiver, value: Date | number, options?: Intl.DateTimeFormatOptions): any;
+    static date(this: Receiver, value: Date | number, options?: Intl.DateTimeFormatOptions): string;
     /**
      * Formats a number through Intl.NumberFormat in the receiver's locale.
      *
      * @param {number} value
      * @param {Intl.NumberFormatOptions} [options]
      * @this {Receiver}
+     * @returns {string}
      */
-    static number(this: Receiver, value: number, options?: Intl.NumberFormatOptions): any;
+    static number(this: Receiver, value: number, options?: Intl.NumberFormatOptions): string;
     /**
      * Formats a byte size with binary thresholds and literal unit suffixes:
      * the digits honor the locale, the units are the near-universal KiB/MiB/GiB.
@@ -701,21 +878,38 @@ declare class Localization {
      *
      * @param {number} value
      * @this {Receiver}
+     * @returns {string}
      */
     static bytes(this: Receiver, value: number): string;
+    /**
+     * 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(this: Receiver, value: any): string;
     /**
      * 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?: {
         locale?: string;
     }): {
-        t: (...args: any[]) => any;
-        date: (...args: any[]) => any;
-        number: (...args: any[]) => any;
-        bytes: (...args: any[]) => any;
+        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;
     };
 }
 export { Attributes, BoundedCache, ExpressionEvaluator, Expressions, Fragments, LightSlots, Localization, Nodes, ParsedElement, Registry, RenderError, Rendering, Template, Templates, registry };