ngx-json-render 0.8.2 → 0.9.1

package/fesm2022/ngx-json-render.mjs

@@ -23,6 +23,11 @@ class JsonRenderRootContext {
      * they apply whatever `validate` is set to.
      */
     limits = EMPTY;
+    /**
+     * The catalog the spec was generated for. While loading, an element whose
+     * props do not pass its component's schema waits for them.
+     */
+    catalog = EMPTY;
     /** External store (controlled mode). */
     store = EMPTY;
     /** Initial state (uncontrolled mode); falls back to `spec.state`. */
@@ -1106,98 +1111,486 @@ function injectDevtoolsActive() {
 }
 
 /**
- * The state paths an element's expressions can read, or `null` when that
- * can't be known from the spec.
+ * A hostile spec can fail the catalog's schema in as many places as it has
+ * properties. Report enough to act on and stop; the spec is refused either
+ * way, and a console full of them helps nobody.
+ */
+const MAX_REPORTED_PROP_ISSUES = 20;
+/**
+ * Whether this element's `repeat` descends into the item it is already inside,
+ * rather than re-reading a fixed path in state.
  *
- * Worked out from the spec alone, before anything resolves, so that an element
- * can depend on those paths rather than on the whole state. The answer may
- * name more paths than a given resolution reads — both branches of a `$cond`,
- * say — but never fewer: a path left out would be a write the element misses,
- * and it would keep showing the old value with nothing in the console.
+ * A relative statePath — `{"$item": "children"}` — resolves against the
+ * enclosing item, so each pass reads one level further into the data and the
+ * recursion ends where the data does. A plain string is absolute: every pass
+ * reads the same array, and a spec that re-enters itself through one never
+ * terminates.
+ */
+function descendsIntoItems(element) {
+    const repeat = element.repeat;
+    return repeat !== undefined && typeof repeat.statePath !== 'string';
+}
+/** Every key an element renders below itself: `children` plus every slot. */
+function childKeysOf(element) {
+    const slots = element.slots;
+    if (!slots)
+        return element.children ?? [];
+    const fromSlots = Object.values(slots).flat();
+    return element.children ? [...element.children, ...fromSlots] : fromSlots;
+}
+/**
+ * Walk the element graph once for depth and cycles.
  *
- * `null` is the safe answer, and it is given whenever the spec holds something
- * this reader does not model:
+ * Iterative on purpose. A recursive walk would blow the stack on exactly the
+ * specs this exists to catch, which would make the guard a second way to
+ * crash rather than the fix for the first.
  *
- * - a registered directive, whose `resolve` receives the whole context and may
- *   read any path at all;
- * - a `$`-prefixed key it doesn't recognise, which is what an expression added
- *   to core after this was written would look like;
- * - a read of the whole state (`''` or `'/'`), and a condition it can't parse.
+ * Depth is measured from `spec.root`, because that is what renders. Cycles
+ * are swept for across every element, including the ones no parent reaches:
+ * an unreachable cycle is still a defect, and one edit away from a reachable
+ * one.
  *
- * The walk mirrors core's `resolvePropValue` and `evaluateVisibility`, in the
- * same order, because the order decides which expression an object is.
+ * Not every element that reaches itself is a defect, though. Drawing a tree —
+ * a comment thread, a file browser, a nested menu — means an element that
+ * repeats over a relative path and renders itself for each item, and that ends
+ * when the data does. A back edge is only reported when nothing along it
+ * descends into the data, which is the case that cannot end.
+ *
+ * `depthBelow` is memoised per element, so a shared subtree costs one visit
+ * instead of one per path into it — without that, a spec whose elements each
+ * name the next two is exponential to check. The memo makes the reported
+ * depth a lower bound once a cycle has been cut, since which edge closes the
+ * cycle depends on the order the walk reached it. The cycle is reported as an
+ * error of its own, which is the finding worth acting on.
  */
-function collectStateReads(element, directives, repeatBasePath) {
-    const reader = new StateReader(directives, repeatBasePath);
-    const understood = reader.condition(element.visible) &&
-        Object.values(element.props ?? {}).every((value) => reader.value(value));
-    return understood ? reader.paths : null;
+function analyseSpecGraph(spec) {
+    const elements = spec.elements ?? {};
+    const cycles = new Set();
+    const depthBelow = new Map();
+    const onPath = new Set();
+    const walkFrom = (start) => {
+        const first = elements[start];
+        if (!first || depthBelow.has(start))
+            return;
+        const stack = [
+            { key: start, kids: childKeysOf(first), next: 0, deepest: 0 },
+        ];
+        onPath.add(start);
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            if (frame.next < frame.kids.length) {
+                const childKey = frame.kids[frame.next++];
+                const memo = depthBelow.get(childKey);
+                if (memo !== undefined) {
+                    frame.deepest = Math.max(frame.deepest, memo);
+                    continue;
+                }
+                // A child that closes the cycle is not followed — that is what keeps
+                // this walk finite — and not counted towards depth either.
+                if (onPath.has(childKey)) {
+                    const from = stack.findIndex((frame) => frame.key === childKey);
+                    const descends = stack
+                        .slice(from)
+                        .some((frame) => descendsIntoItems(elements[frame.key]));
+                    if (!descends)
+                        cycles.add(childKey);
+                    continue;
+                }
+                const child = elements[childKey];
+                // A child the spec never defined is validateSpec's finding, not ours.
+                if (!child)
+                    continue;
+                onPath.add(childKey);
+                stack.push({
+                    key: childKey,
+                    kids: childKeysOf(child),
+                    next: 0,
+                    deepest: 0,
+                });
+                continue;
+            }
+            stack.pop();
+            onPath.delete(frame.key);
+            const depth = frame.deepest + 1;
+            depthBelow.set(frame.key, depth);
+            const parent = stack[stack.length - 1];
+            if (parent)
+                parent.deepest = Math.max(parent.deepest, depth);
+        }
+    };
+    if (spec.root)
+        walkFrom(spec.root);
+    const depth = (spec.root ? depthBelow.get(spec.root) : undefined) ?? 0;
+    for (const key of Object.keys(elements))
+        walkFrom(key);
+    return { depth, cycles: [...cycles] };
 }
-function isObject(value) {
-    return typeof value === 'object' && value !== null;
+/** Report a cycle, naming the element that is its own descendant. */
+function cycleIssue(key) {
+    return {
+        severity: 'error',
+        code: 'cycle',
+        elementKey: key,
+        message: `Element "${key}" renders itself against the same data, which never terminates. The cycle is broken where it closes — the repeated element does not render a second time — but the spec cannot be drawn as written. A tree that recurses needs a repeat with a relative statePath, like {"$item": "children"}.`,
+    };
 }
-/** Comparison operators a single condition may carry, as core reads them. */
-const COMPARISONS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte'];
-class StateReader {
-    directives;
-    repeatBasePath;
-    paths = new Set();
-    constructor(directives, repeatBasePath) {
-        this.directives = directives;
-        this.repeatBasePath = repeatBasePath;
+/** Report a breached element-count cap. */
+function elementCountIssue(count, limit) {
+    return {
+        severity: 'error',
+        code: 'too_many_elements',
+        message: `Spec has ${count} elements, over the limit of ${limit}. Nothing is rendered: renderLimits.maxElements is a cap on the whole spec.`,
+    };
+}
+/** Report a breached depth cap. */
+function depthIssue(depth, limit) {
+    return {
+        severity: 'error',
+        code: 'too_deep',
+        message: `Spec nests ${depth} levels deep, over the limit of ${limit}. Elements below level ${limit} do not render.`,
+    };
+}
+/**
+ * Check a spec against a catalog: the component types it names, then the
+ * catalog's spec schema, then each element's props against its own
+ * component's schema.
+ *
+ * The props need that pass of their own. Core builds one schema for the whole
+ * spec, and it gives an element's props a component's schema only when the
+ * catalog has exactly one component; with more, every element's props are an
+ * open record, whatever its `type`. So `catalog.validate` holds an element to
+ * its shape — `children`, a `type` from the catalog — and not to its props.
+ *
+ * Whatever that schema did say about the props of an element checked here is
+ * dropped: with a one-component catalog it would be reported twice, and it
+ * judges expressions this pass knows to leave alone.
+ *
+ * The schema passes are skipped while a type is unknown. That is an error on
+ * its own, and the spec schema would only restate it as a `type` outside the
+ * ones it accepts.
+ */
+function catalogIssues(spec, catalog) {
+    const elements = Object.entries(spec.elements ?? {});
+    const known = new Set(catalog.componentNames);
+    const unknown = [];
+    for (const [key, element] of elements) {
+        if (known.has(element.type))
+            continue;
+        unknown.push({
+            severity: 'error',
+            code: 'unknown_component',
+            elementKey: key,
+            message: `Element "${key}" has type "${element.type}", which this catalog does not define. Nothing renders for it.`,
+        });
     }
-    /** A prop value. Returns false when it can read state this can't name. */
-    value(value) {
-        if (!isObject(value))
-            return true;
-        if (typeof value['$state'] === 'string')
-            return this.state(value['$state']);
-        if (typeof value['$item'] === 'string')
-            return this.item(value['$item']);
-        if ('$index' in value && value['$index'] === true)
-            return true;
-        // A two-way binding reads the path it writes back to.
-        if (typeof value['$bindState'] === 'string') {
-            return this.state(value['$bindState']);
-        }
-        if (typeof value['$bindItem'] === 'string') {
-            return this.boundItem(value['$bindItem']);
-        }
-        if ('$cond' in value && '$then' in value && '$else' in value) {
-            return (this.condition(value['$cond']) &&
-                this.value(value['$then']) &&
-                this.value(value['$else']));
-        }
-        if (typeof value['$computed'] === 'string') {
-            // The function is handed its resolved arguments and nothing else.
-            const args = value['args'];
-            return (!args || Object.values(Object(args)).every((arg) => this.value(arg)));
-        }
-        if (typeof value['$template'] === 'string') {
-            return this.template(value['$template']);
-        }
-        if (Array.isArray(value))
-            return value.every((item) => this.value(item));
-        if (this.directives) {
-            for (const name of this.directives.keys()) {
-                if (name in value)
-                    return false;
-            }
-        }
-        for (const [key, entry] of Object.entries(value)) {
-            if (key.startsWith('$') || !this.value(entry))
-                return false;
-        }
-        return true;
+    if (unknown.length > 0)
+        return unknown;
+    const schemas = new Map();
+    for (const [key, element] of elements) {
+        const schema = propsSchemaOf(catalog.data, element.type);
+        if (schema)
+            schemas.set(key, schema);
     }
-    /** A `visible` condition, or the condition of a `$cond`. */
-    condition(condition) {
-        if (condition === undefined || typeof condition === 'boolean')
-            return true;
-        if (Array.isArray(condition)) {
-            return condition.every((single) => this.singleCondition(single));
-        }
-        if (!isObject(condition))
+    const found = specSchemaIssues(spec, catalog).filter(({ path }) => !(path[0] === 'elements' &&
+        typeof path[1] === 'string' &&
+        schemas.has(path[1]) &&
+        path[2] === 'props'));
+    for (const [key, element] of elements) {
+        const room = MAX_REPORTED_PROP_ISSUES - found.length;
+        if (room <= 0)
+            break;
+        const schema = schemas.get(key);
+        if (schema)
+            found.push(...propsIssues(key, element, schema, room));
+    }
+    return found.slice(0, MAX_REPORTED_PROP_ISSUES).map(toSpecCheckIssue);
+}
+/**
+ * Whether an element's props have arrived: they pass its component's schema,
+ * leaving out what the schema says about expressions, the same way
+ * {@link catalogIssues} judges them. The renderer holds an element back on
+ * this while the spec streams.
+ *
+ * The props are taken as written in the spec, not as resolved. What a stream
+ * leaves out is spec, and an expression that is there has arrived, whatever
+ * it resolves to; checking the spec also keeps state writes from re-running
+ * the schema.
+ *
+ * True when the catalog declares no schema that can be called for the type:
+ * there is nothing to wait for. False when the schema throws, or fails
+ * without saying where — the element mounts once loading ends either way.
+ */
+function propsArrived(element, catalog) {
+    const schema = propsSchemaOf(catalog.data, element.type);
+    if (!schema)
+        return true;
+    const props = element.props ?? {};
+    let result;
+    try {
+        result = schema.safeParse(props);
+    }
+    catch {
+        return false;
+    }
+    if (result.success)
+        return true;
+    const issues = readIssues(result.error);
+    return (issues.length > 0 &&
+        issues.every(({ path }) => reachesExpression(props, path)));
+}
+/**
+ * The props schema a catalog declares for a component type, if it declares
+ * one that can be called.
+ */
+function propsSchemaOf(data, type) {
+    const components = data
+        ?.components;
+    if (typeof components !== 'object' ||
+        components === null ||
+        !Object.hasOwn(components, type)) {
+        return undefined;
+    }
+    const props = components[type]?.props;
+    return typeof props
+        ?.safeParse === 'function'
+        ? props
+        : undefined;
+}
+/** What the catalog's spec schema reported, with paths rooted at the spec. */
+function specSchemaIssues(spec, catalog) {
+    try {
+        const result = catalog.validate(spec);
+        return result.success ? [] : readIssues(result.error);
+    }
+    catch (error) {
+        return [{ path: [], message: threwMessage('the catalog schema', error) }];
+    }
+}
+/**
+ * What an element's component schema says about its props, leaving out what
+ * it says about expressions, with paths rooted at the spec.
+ *
+ * A schema that throws counts as a rejection, not a crash. Real ones do:
+ * `ValidationConfigSchema`, which every Material input's `validation` prop
+ * uses, recurses through `enabled` and overflows the stack a thousand
+ * `$and`s deep.
+ */
+function propsIssues(key, element, schema, room) {
+    const at = ['elements', key, 'props'];
+    let result;
+    try {
+        result = schema.safeParse(element.props);
+    }
+    catch (error) {
+        return [
+            {
+                path: at,
+                message: threwMessage(`the "${element.type}" schema`, error),
+            },
+        ];
+    }
+    if (result.success)
+        return [];
+    const issues = [];
+    for (const { path, message } of readIssues(result.error)) {
+        if (issues.length >= room)
+            break;
+        if (reachesExpression(element.props, path))
+            continue;
+        issues.push({ path: [...at, ...path], message });
+    }
+    return issues;
+}
+/**
+ * Whether a props issue is about an expression: it sits on one, inside one,
+ * or on a value holding one.
+ *
+ * `{"$state": "/title"}` where the schema wants a string is not a defect.
+ * Core resolves every such value before the component sees it, so the schema
+ * would be judging something that never renders. Any `$`-prefixed key counts
+ * — directive names must start with `$`, and so would an expression added to
+ * core later. A value merely holding one is left alone too, since a union or
+ * a refinement over it ran on the unresolved value.
+ *
+ * The props object itself is not an expression: core resolves the values
+ * inside it, never the object.
+ */
+function reachesExpression(props, path) {
+    let value = props;
+    for (const segment of path) {
+        if (typeof value !== 'object' || value === null)
+            return false;
+        value = value[segment];
+        if (isExpression(value))
+            return true;
+    }
+    return holdsExpression(value);
+}
+/** A value core resolves at render time — or will, once it knows the key. */
+function isExpression(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).some((key) => key.startsWith('$')));
+}
+/**
+ * Whether anything nested inside `value` is an expression.
+ *
+ * Iterative, and it remembers what it has seen, for the same reason as
+ * {@link analyseSpecGraph}: props are as attacker-shaped as the rest of the
+ * spec, and a check that overflowed or looped on them would be a second way
+ * to crash.
+ */
+function holdsExpression(value) {
+    const pending = [value];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (typeof current !== 'object' || current === null)
+            continue;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        for (const child of Object.values(current)) {
+            if (isExpression(child))
+                return true;
+            pending.push(child);
+        }
+    }
+    return false;
+}
+/**
+ * Read what a schema reported.
+ *
+ * Read defensively rather than typed against the schema library: the shape
+ * below (`issues`, each with `path` and `message`) is what every version of
+ * it has produced, and a renderer that threw while explaining a bad spec
+ * would be the worse failure.
+ */
+function readIssues(error) {
+    const raw = error?.issues;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((entry) => {
+        const item = entry;
+        const path = item?.path;
+        const message = item?.message;
+        return {
+            path: Array.isArray(path) ? path : [],
+            message: typeof message === 'string' ? message : 'is not valid',
+        };
+    });
+}
+function threwMessage(schema, error) {
+    const reason = error instanceof Error ? ` (${error.name}: ${error.message})` : '';
+    return `${schema} threw instead of answering${reason}, so this counts as rejected`;
+}
+function toSpecCheckIssue({ path, message }) {
+    // Paths are rooted at the spec, so `elements.<key>.props.<prop>` names the
+    // element in its second segment.
+    const elementKey = path[0] === 'elements' && typeof path[1] === 'string' ? path[1] : undefined;
+    const where = path.length > 0 ? path.map(String).join('.') : 'spec';
+    return {
+        severity: 'error',
+        code: 'invalid_props',
+        ...(elementKey === undefined ? {} : { elementKey }),
+        message: `${where}: ${message}`,
+    };
+}
+
+/**
+ * The state paths an element's expressions can read, or `null` when that
+ * can't be known from the spec.
+ *
+ * Worked out from the spec alone, before anything resolves, so that an element
+ * can depend on those paths rather than on the whole state. The answer may
+ * name more paths than a given resolution reads — both branches of a `$cond`,
+ * say — but never fewer: a path left out would be a write the element misses,
+ * and it would keep showing the old value with nothing in the console.
+ *
+ * `null` is the safe answer, and it is given whenever the spec holds something
+ * this reader does not model:
+ *
+ * - a registered directive, whose `resolve` receives the whole context and may
+ *   read any path at all;
+ * - a `$`-prefixed key it doesn't recognise, which is what an expression added
+ *   to core after this was written would look like;
+ * - a read of the whole state (`''` or `'/'`), and a condition it can't parse.
+ *
+ * The walk mirrors core's `resolvePropValue` and `evaluateVisibility`, in the
+ * same order, because the order decides which expression an object is.
+ */
+function collectStateReads(element, directives, repeatBasePath) {
+    const reader = new StateReader(directives, repeatBasePath);
+    const understood = reader.condition(element.visible) &&
+        Object.values(element.props ?? {}).every((value) => reader.value(value));
+    return understood ? reader.paths : null;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Comparison operators a single condition may carry, as core reads them. */
+const COMPARISONS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte'];
+class StateReader {
+    directives;
+    repeatBasePath;
+    paths = new Set();
+    constructor(directives, repeatBasePath) {
+        this.directives = directives;
+        this.repeatBasePath = repeatBasePath;
+    }
+    /** A prop value. Returns false when it can read state this can't name. */
+    value(value) {
+        if (!isObject(value))
+            return true;
+        if (typeof value['$state'] === 'string')
+            return this.state(value['$state']);
+        if (typeof value['$item'] === 'string')
+            return this.item(value['$item']);
+        if ('$index' in value && value['$index'] === true)
+            return true;
+        // A two-way binding reads the path it writes back to.
+        if (typeof value['$bindState'] === 'string') {
+            return this.state(value['$bindState']);
+        }
+        if (typeof value['$bindItem'] === 'string') {
+            return this.boundItem(value['$bindItem']);
+        }
+        if ('$cond' in value && '$then' in value && '$else' in value) {
+            return (this.condition(value['$cond']) &&
+                this.value(value['$then']) &&
+                this.value(value['$else']));
+        }
+        if (typeof value['$computed'] === 'string') {
+            // The function is handed its resolved arguments and nothing else.
+            const args = value['args'];
+            return (!args || Object.values(Object(args)).every((arg) => this.value(arg)));
+        }
+        if (typeof value['$template'] === 'string') {
+            return this.template(value['$template']);
+        }
+        if (Array.isArray(value))
+            return value.every((item) => this.value(item));
+        if (this.directives) {
+            for (const name of this.directives.keys()) {
+                if (name in value)
+                    return false;
+            }
+        }
+        for (const [key, entry] of Object.entries(value)) {
+            if (key.startsWith('$') || !this.value(entry))
+                return false;
+        }
+        return true;
+    }
+    /** A `visible` condition, or the condition of a `$cond`. */
+    condition(condition) {
+        if (condition === undefined || typeof condition === 'boolean')
+            return true;
+        if (Array.isArray(condition)) {
+            return condition.every((single) => this.singleCondition(single));
+        }
+        if (!isObject(condition))
             return false;
         for (const group of ['$and', '$or']) {
             if (group in condition) {
@@ -1668,7 +2061,34 @@ class JrElement {
         const el = this.rawElement();
         return el ? this.root.resolveEntry(el.type) : undefined;
     }, ...(ngDevMode ? [{ debugName: "entry" }] : /* istanbul ignore next */ []));
-    component = computed(() => this.entry()?.component ?? null, ...(ngDevMode ? [{ debugName: "component" }] : /* istanbul ignore next */ []));
+    /** Set once the real component has been shown; see {@link held}. */
+    mounted = false;
+    /**
+     * Whether the component waits for its props: the spec is still loading, a
+     * catalog was given, and the props written so far do not pass the
+     * component's schema (see {@link propsArrived}).
+     *
+     * One-way. Once the component has been shown it is never swapped back for
+     * the fallback, even if a later patch takes a prop away again: a component
+     * flickering out mid-stream is worse than one showing a gap. Once latched
+     * this reads no signals, so a mounted element pays nothing for the gate on
+     * later patches — and neither does any element when nothing is loading.
+     */
+    held = computed(() => {
+        if (this.mounted)
+            return false;
+        const el = this.rawElement();
+        const catalog = this.root.catalog();
+        const held = !!el && !!catalog && this.root.loading() && !propsArrived(el, catalog);
+        if (!held && this.entry() && this.visible() && !this.refusal()) {
+            this.mounted = true;
+        }
+        return held;
+    }, ...(ngDevMode ? [{ debugName: "held" }] : /* istanbul ignore next */ []));
+    /** What the outlet shows: the component, or its fallback while held. */
+    component = computed(() => this.held()
+        ? (this.entry()?.fallback ?? null)
+        : (this.entry()?.component ?? null), ...(ngDevMode ? [{ debugName: "component" }] : /* istanbul ignore next */ []));
     devtoolsKey = computed(() => this.devtoolsActive() ? this.elementKey() : null, ...(ngDevMode ? [{ debugName: "devtoolsKey" }] : /* istanbul ignore next */ []));
     /**
      * Where this element sits in the tree. Passed down to everything it renders
@@ -1884,432 +2304,163 @@ class JrElement {
             stateModel: this.state.getSnapshot(),
         };
     }
-    /**
-     * Fire-and-forget entry point for event emission: dispatching is async, but
-     * a template listener has nowhere to await it, so the failure must be
-     * handled here rather than escaping as an unhandled rejection.
-     */
-    fireEvent(eventName) {
-        this.emitEvent(eventName).catch(reportActionError);
-    }
-    async emitEvent(eventName) {
-        const binding = untracked(this.rawElement)?.on?.[eventName];
-        if (binding)
-            await this.dispatch(binding);
-    }
-    /**
-     * Run an `on` or `watch` binding's actions in order. Params are resolved
-     * per action, just before it runs, so a `$state` read in a later action of
-     * the chain sees what an earlier one wrote.
-     */
-    async dispatch(binding) {
-        for (const b of Array.isArray(binding) ? binding : [binding]) {
-            if (!b.params) {
-                await this.actions.execute(b);
-                continue;
-            }
-            const liveCtx = this.liveResolutionCtx();
-            const resolved = {};
-            for (const [key, val] of Object.entries(b.params)) {
-                resolved[key] = resolveActionParam(val, liveCtx);
-            }
-            await this.actions.execute({ ...b, params: resolved });
-        }
-    }
-    eventHandle(eventName) {
-        const el = this.rawElement();
-        const binding = el?.on?.[eventName];
-        if (!binding) {
-            return { emit: () => { }, shouldPreventDefault: false, bound: false };
-        }
-        const actionBindings = Array.isArray(binding) ? binding : [binding];
-        return {
-            emit: () => this.fireEvent(eventName),
-            shouldPreventDefault: actionBindings.some((b) => b.preventDefault),
-            bound: true,
-        };
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JrElement, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JrElement, isStandalone: true, selector: "jr-element", inputs: { elementKey: { classPropertyName: "elementKey", publicName: "elementKey", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0, template: `
-    @if (!refusal() && rawElement() && visible() && component()) {
-      @if (devtoolsKey(); as dk) {
-        <span [attr.data-jr-key]="dk" style="display: contents">
-          <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
-        </span>
-      } @else {
-        <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
-      }
-    }
-  `, isInline: true, styles: [":host{display:contents}\n"], dependencies: [{ kind: "directive", type: NgComponentOutlet, selector: "[ngComponentOutlet]", inputs: ["ngComponentOutlet", "ngComponentOutletInputs", "ngComponentOutletInjector", "ngComponentOutletEnvironmentInjector", "ngComponentOutletContent", "ngComponentOutletNgModule"], exportAs: ["ngComponentOutlet"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JrElement, decorators: [{
-            type: Component,
-            args: [{ selector: 'jr-element', changeDetection: ChangeDetectionStrategy.OnPush, imports: [NgComponentOutlet], template: `
-    @if (!refusal() && rawElement() && visible() && component()) {
-      @if (devtoolsKey(); as dk) {
-        <span [attr.data-jr-key]="dk" style="display: contents">
-          <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
-        </span>
-      } @else {
-        <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
-      }
-    }
-  `, styles: [":host{display:contents}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { elementKey: [{ type: i0.Input, args: [{ isSignal: true, alias: "elementKey", required: true }] }] } });
-
-/**
- * A hostile spec can fail the catalog's schema in as many places as it has
- * properties. Report enough to act on and stop; the spec is refused either
- * way, and a console full of them helps nobody.
- */
-const MAX_REPORTED_PROP_ISSUES = 20;
-/**
- * Whether this element's `repeat` descends into the item it is already inside,
- * rather than re-reading a fixed path in state.
- *
- * A relative statePath — `{"$item": "children"}` — resolves against the
- * enclosing item, so each pass reads one level further into the data and the
- * recursion ends where the data does. A plain string is absolute: every pass
- * reads the same array, and a spec that re-enters itself through one never
- * terminates.
- */
-function descendsIntoItems(element) {
-    const repeat = element.repeat;
-    return repeat !== undefined && typeof repeat.statePath !== 'string';
-}
-/** Every key an element renders below itself: `children` plus every slot. */
-function childKeysOf(element) {
-    const slots = element.slots;
-    if (!slots)
-        return element.children ?? [];
-    const fromSlots = Object.values(slots).flat();
-    return element.children ? [...element.children, ...fromSlots] : fromSlots;
-}
-/**
- * Walk the element graph once for depth and cycles.
- *
- * Iterative on purpose. A recursive walk would blow the stack on exactly the
- * specs this exists to catch, which would make the guard a second way to
- * crash rather than the fix for the first.
- *
- * Depth is measured from `spec.root`, because that is what renders. Cycles
- * are swept for across every element, including the ones no parent reaches:
- * an unreachable cycle is still a defect, and one edit away from a reachable
- * one.
- *
- * Not every element that reaches itself is a defect, though. Drawing a tree —
- * a comment thread, a file browser, a nested menu — means an element that
- * repeats over a relative path and renders itself for each item, and that ends
- * when the data does. A back edge is only reported when nothing along it
- * descends into the data, which is the case that cannot end.
- *
- * `depthBelow` is memoised per element, so a shared subtree costs one visit
- * instead of one per path into it — without that, a spec whose elements each
- * name the next two is exponential to check. The memo makes the reported
- * depth a lower bound once a cycle has been cut, since which edge closes the
- * cycle depends on the order the walk reached it. The cycle is reported as an
- * error of its own, which is the finding worth acting on.
- */
-function analyseSpecGraph(spec) {
-    const elements = spec.elements ?? {};
-    const cycles = new Set();
-    const depthBelow = new Map();
-    const onPath = new Set();
-    const walkFrom = (start) => {
-        const first = elements[start];
-        if (!first || depthBelow.has(start))
-            return;
-        const stack = [
-            { key: start, kids: childKeysOf(first), next: 0, deepest: 0 },
-        ];
-        onPath.add(start);
-        while (stack.length > 0) {
-            const frame = stack[stack.length - 1];
-            if (frame.next < frame.kids.length) {
-                const childKey = frame.kids[frame.next++];
-                const memo = depthBelow.get(childKey);
-                if (memo !== undefined) {
-                    frame.deepest = Math.max(frame.deepest, memo);
-                    continue;
-                }
-                // A child that closes the cycle is not followed — that is what keeps
-                // this walk finite — and not counted towards depth either.
-                if (onPath.has(childKey)) {
-                    const from = stack.findIndex((frame) => frame.key === childKey);
-                    const descends = stack
-                        .slice(from)
-                        .some((frame) => descendsIntoItems(elements[frame.key]));
-                    if (!descends)
-                        cycles.add(childKey);
-                    continue;
-                }
-                const child = elements[childKey];
-                // A child the spec never defined is validateSpec's finding, not ours.
-                if (!child)
-                    continue;
-                onPath.add(childKey);
-                stack.push({
-                    key: childKey,
-                    kids: childKeysOf(child),
-                    next: 0,
-                    deepest: 0,
-                });
-                continue;
-            }
-            stack.pop();
-            onPath.delete(frame.key);
-            const depth = frame.deepest + 1;
-            depthBelow.set(frame.key, depth);
-            const parent = stack[stack.length - 1];
-            if (parent)
-                parent.deepest = Math.max(parent.deepest, depth);
-        }
-    };
-    if (spec.root)
-        walkFrom(spec.root);
-    const depth = (spec.root ? depthBelow.get(spec.root) : undefined) ?? 0;
-    for (const key of Object.keys(elements))
-        walkFrom(key);
-    return { depth, cycles: [...cycles] };
-}
-/** Report a cycle, naming the element that is its own descendant. */
-function cycleIssue(key) {
-    return {
-        severity: 'error',
-        code: 'cycle',
-        elementKey: key,
-        message: `Element "${key}" renders itself against the same data, which never terminates. The cycle is broken where it closes — the repeated element does not render a second time — but the spec cannot be drawn as written. A tree that recurses needs a repeat with a relative statePath, like {"$item": "children"}.`,
-    };
-}
-/** Report a breached element-count cap. */
-function elementCountIssue(count, limit) {
-    return {
-        severity: 'error',
-        code: 'too_many_elements',
-        message: `Spec has ${count} elements, over the limit of ${limit}. Nothing is rendered: renderLimits.maxElements is a cap on the whole spec.`,
-    };
-}
-/** Report a breached depth cap. */
-function depthIssue(depth, limit) {
-    return {
-        severity: 'error',
-        code: 'too_deep',
-        message: `Spec nests ${depth} levels deep, over the limit of ${limit}. Elements below level ${limit} do not render.`,
-    };
-}
-/**
- * Check a spec against a catalog: the component types it names, then the
- * catalog's spec schema, then each element's props against its own
- * component's schema.
- *
- * The props need that pass of their own. Core builds one schema for the whole
- * spec, and it gives an element's props a component's schema only when the
- * catalog has exactly one component; with more, every element's props are an
- * open record, whatever its `type`. So `catalog.validate` holds an element to
- * its shape — `children`, a `type` from the catalog — and not to its props.
- *
- * Whatever that schema did say about the props of an element checked here is
- * dropped: with a one-component catalog it would be reported twice, and it
- * judges expressions this pass knows to leave alone.
- *
- * The schema passes are skipped while a type is unknown. That is an error on
- * its own, and the spec schema would only restate it as a `type` outside the
- * ones it accepts.
- */
-function catalogIssues(spec, catalog) {
-    const elements = Object.entries(spec.elements ?? {});
-    const known = new Set(catalog.componentNames);
-    const unknown = [];
-    for (const [key, element] of elements) {
-        if (known.has(element.type))
-            continue;
-        unknown.push({
-            severity: 'error',
-            code: 'unknown_component',
-            elementKey: key,
-            message: `Element "${key}" has type "${element.type}", which this catalog does not define. Nothing renders for it.`,
-        });
-    }
-    if (unknown.length > 0)
-        return unknown;
-    const schemas = new Map();
-    for (const [key, element] of elements) {
-        const schema = propsSchemaOf(catalog.data, element.type);
-        if (schema)
-            schemas.set(key, schema);
+    /**
+     * Fire-and-forget entry point for event emission: dispatching is async, but
+     * a template listener has nowhere to await it, so the failure must be
+     * handled here rather than escaping as an unhandled rejection.
+     */
+    fireEvent(eventName) {
+        this.emitEvent(eventName).catch(reportActionError);
     }
-    const found = specSchemaIssues(spec, catalog).filter(({ path }) => !(path[0] === 'elements' &&
-        typeof path[1] === 'string' &&
-        schemas.has(path[1]) &&
-        path[2] === 'props'));
-    for (const [key, element] of elements) {
-        const room = MAX_REPORTED_PROP_ISSUES - found.length;
-        if (room <= 0)
-            break;
-        const schema = schemas.get(key);
-        if (schema)
-            found.push(...propsIssues(key, element, schema, room));
+    async emitEvent(eventName) {
+        const binding = untracked(this.rawElement)?.on?.[eventName];
+        if (binding)
+            await this.dispatch(binding);
     }
-    return found.slice(0, MAX_REPORTED_PROP_ISSUES).map(toSpecCheckIssue);
-}
-/**
- * The props schema a catalog declares for a component type, if it declares
- * one that can be called.
- */
-function propsSchemaOf(data, type) {
-    const components = data
-        ?.components;
-    if (typeof components !== 'object' ||
-        components === null ||
-        !Object.hasOwn(components, type)) {
-        return undefined;
+    /**
+     * Run an `on` or `watch` binding's actions in order. Params are resolved
+     * per action, just before it runs, so a `$state` read in a later action of
+     * the chain sees what an earlier one wrote.
+     */
+    async dispatch(binding) {
+        for (const b of Array.isArray(binding) ? binding : [binding]) {
+            if (!b.params) {
+                await this.actions.execute(b);
+                continue;
+            }
+            const liveCtx = this.liveResolutionCtx();
+            const resolved = {};
+            for (const [key, val] of Object.entries(b.params)) {
+                resolved[key] = resolveActionParam(val, liveCtx);
+            }
+            await this.actions.execute({ ...b, params: resolved });
+        }
     }
-    const props = components[type]?.props;
-    return typeof props
-        ?.safeParse === 'function'
-        ? props
-        : undefined;
-}
-/** What the catalog's spec schema reported, with paths rooted at the spec. */
-function specSchemaIssues(spec, catalog) {
-    try {
-        const result = catalog.validate(spec);
-        return result.success ? [] : readIssues(result.error);
+    eventHandle(eventName) {
+        const el = this.rawElement();
+        const binding = el?.on?.[eventName];
+        if (!binding) {
+            return { emit: () => { }, shouldPreventDefault: false, bound: false };
+        }
+        const actionBindings = Array.isArray(binding) ? binding : [binding];
+        return {
+            emit: () => this.fireEvent(eventName),
+            shouldPreventDefault: actionBindings.some((b) => b.preventDefault),
+            bound: true,
+        };
     }
-    catch (error) {
-        return [{ path: [], message: threwMessage('the catalog schema', error) }];
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JrElement, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JrElement, isStandalone: true, selector: "jr-element", inputs: { elementKey: { classPropertyName: "elementKey", publicName: "elementKey", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0, template: `
+    @if (!refusal() && rawElement() && visible() && component()) {
+      @if (devtoolsKey(); as dk) {
+        <span [attr.data-jr-key]="dk" style="display: contents">
+          <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
+        </span>
+      } @else {
+        <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
+      }
     }
+  `, isInline: true, styles: [":host{display:contents}\n"], dependencies: [{ kind: "directive", type: NgComponentOutlet, selector: "[ngComponentOutlet]", inputs: ["ngComponentOutlet", "ngComponentOutletInputs", "ngComponentOutletInjector", "ngComponentOutletEnvironmentInjector", "ngComponentOutletContent", "ngComponentOutletNgModule"], exportAs: ["ngComponentOutlet"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JrElement, decorators: [{
+            type: Component,
+            args: [{ selector: 'jr-element', changeDetection: ChangeDetectionStrategy.OnPush, imports: [NgComponentOutlet], template: `
+    @if (!refusal() && rawElement() && visible() && component()) {
+      @if (devtoolsKey(); as dk) {
+        <span [attr.data-jr-key]="dk" style="display: contents">
+          <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
+        </span>
+      } @else {
+        <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
+      }
+    }
+  `, styles: [":host{display:contents}\n"] }]
+        }], ctorParameters: () => [], propDecorators: { elementKey: [{ type: i0.Input, args: [{ isSignal: true, alias: "elementKey", required: true }] }] } });
+
 /**
- * What an element's component schema says about its props, leaving out what
- * it says about expressions, with paths rooted at the spec.
- *
- * A schema that throws counts as a rejection, not a crash. Real ones do:
- * `ValidationConfigSchema`, which every Material input's `validation` prop
- * uses, recurses through `enabled` and overflows the stack a thousand
- * `$and`s deep.
+ * The defaults the nearest {@link provideJsonRender} supplies, already merged
+ * with any provider above it.
  */
-function propsIssues(key, element, schema, room) {
-    const at = ['elements', key, 'props'];
-    let result;
-    try {
-        result = schema.safeParse(element.props);
-    }
-    catch (error) {
-        return [
-            {
-                path: at,
-                message: threwMessage(`the "${element.type}" schema`, error),
-            },
-        ];
-    }
-    if (result.success)
-        return [];
-    const issues = [];
-    for (const { path, message } of readIssues(result.error)) {
-        if (issues.length >= room)
-            break;
-        if (reachesExpression(element.props, path))
-            continue;
-        issues.push({ path: [...at, ...path], message });
-    }
-    return issues;
-}
+const JSON_RENDER_CONFIG = new InjectionToken('JSON_RENDER_CONFIG');
 /**
- * Whether a props issue is about an expression: it sits on one, inside one,
- * or on a value holding one.
+ * Set renderer defaults once instead of on every `<json-render>`:
  *
- * `{"$state": "/title"}` where the schema wants a string is not a defect.
- * Core resolves every such value before the component sees it, so the schema
- * would be judging something that never renders. Any `$`-prefixed key counts
- * — directive names must start with `$`, and so would an expression added to
- * core later. A value merely holding one is left alone too, since a union or
- * a refinement over it ran on the unresolved value.
+ * ```ts
+ * bootstrapApplication(App, { providers: [provideJsonRender({ registry })] });
+ * ```
  *
- * The props object itself is not an expression: core resolves the values
- * inside it, never the object.
- */
-function reachesExpression(props, path) {
-    let value = props;
-    for (const segment of path) {
-        if (typeof value !== 'object' || value === null)
-            return false;
-        value = value[segment];
-        if (isExpression(value))
-            return true;
-    }
-    return holdsExpression(value);
+ * ```html
+ * <json-render [spec]="m.spec" />
+ * ```
+ *
+ * Pass a function to build the defaults with `inject()`, for handlers that
+ * call your services:
+ *
+ * ```ts
+ * provideJsonRender(() => {
+ *   const orders = inject(OrderService);
+ *   return { registry, handlers: { cancelOrder: (p) => orders.cancel(p['id']) } };
+ * });
+ * ```
+ *
+ * Works in application, route and component `providers`. A provider below
+ * another extends it with the same rules an element input does: its own
+ * values replace, its named vocabularies merge.
+ */
+function provideJsonRender(config) {
+    return [
+        {
+            provide: JSON_RENDER_CONFIG,
+            useFactory: () => {
+                const outer = inject(JSON_RENDER_CONFIG, {
+                    optional: true,
+                    skipSelf: true,
+                });
+                const own = typeof config === 'function' ? config() : config;
+                return outer ? mergeJsonRenderConfig(outer, own) : own;
+            },
+        },
+    ];
 }
-/** A value core resolves at render time — or will, once it knows the key. */
-function isExpression(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        !Array.isArray(value) &&
-        Object.keys(value).some((key) => key.startsWith('$')));
+/** `inner` over `outer`, by the rules {@link JsonRenderConfig} describes. */
+function mergeJsonRenderConfig(outer, inner) {
+    const merged = { ...outer };
+    for (const [key, value] of Object.entries(inner)) {
+        if (value !== undefined && value !== null) {
+            merged[key] = value;
+        }
+    }
+    merged.handlers = mergeByName(outer.handlers, inner.handlers);
+    merged.functions = mergeByName(outer.functions, inner.functions);
+    merged.validationFunctions = mergeByName(outer.validationFunctions, inner.validationFunctions);
+    merged.directives = mergeDirectives(outer.directives, inner.directives);
+    return merged;
 }
 /**
- * Whether anything nested inside `value` is an expression.
+ * Two name → value maps as one, `inner` winning a name both define. Returns
+ * whichever is given when only one is, so an unmerged map keeps its identity.
  *
- * Iterative, and it remembers what it has seen, for the same reason as
- * {@link analyseSpecGraph}: props are as attacker-shaped as the rest of the
- * spec, and a check that overflowed or looped on them would be a second way
- * to crash.
+ * @internal
  */
-function holdsExpression(value) {
-    const pending = [value];
-    const seen = new Set();
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (typeof current !== 'object' || current === null)
-            continue;
-        if (seen.has(current))
-            continue;
-        seen.add(current);
-        for (const child of Object.values(current)) {
-            if (isExpression(child))
-                return true;
-            pending.push(child);
-        }
-    }
-    return false;
+function mergeByName(outer, inner) {
+    if (!outer)
+        return inner ?? undefined;
+    if (!inner)
+        return outer;
+    return { ...outer, ...inner };
 }
 /**
- * Read what a schema reported.
+ * Two directive lists as one, `inner` winning a name both define — the
+ * directive registry keeps the last definition of a name.
  *
- * Read defensively rather than typed against the schema library: the shape
- * below (`issues`, each with `path` and `message`) is what every version of
- * it has produced, and a renderer that threw while explaining a bad spec
- * would be the worse failure.
+ * @internal
  */
-function readIssues(error) {
-    const raw = error?.issues;
-    if (!Array.isArray(raw))
-        return [];
-    return raw.map((entry) => {
-        const item = entry;
-        const path = item?.path;
-        const message = item?.message;
-        return {
-            path: Array.isArray(path) ? path : [],
-            message: typeof message === 'string' ? message : 'is not valid',
-        };
-    });
-}
-function threwMessage(schema, error) {
-    const reason = error instanceof Error ? ` (${error.name}: ${error.message})` : '';
-    return `${schema} threw instead of answering${reason}, so this counts as rejected`;
-}
-function toSpecCheckIssue({ path, message }) {
-    // Paths are rooted at the spec, so `elements.<key>.props.<prop>` names the
-    // element in its second segment.
-    const elementKey = path[0] === 'elements' && typeof path[1] === 'string' ? path[1] : undefined;
-    const where = path.length > 0 ? path.map(String).join('.') : 'spec';
-    return {
-        severity: 'error',
-        code: 'invalid_props',
-        ...(elementKey === undefined ? {} : { elementKey }),
-        message: `${where}: ${message}`,
-    };
+function mergeDirectives(outer, inner) {
+    if (!outer)
+        return inner ?? undefined;
+    if (!inner)
+        return outer;
+    return [...outer, ...inner];
 }
 
 const CLEAN = {
@@ -2461,8 +2612,11 @@ function reportSpecCheck(check, mode) {
 class JsonRenderer {
     /** The UI spec to render (may be partial while streaming). */
     spec = input.required(...(ngDevMode ? [{ debugName: "spec" }] : /* istanbul ignore next */ []));
-    /** Component registry mapping catalog type names to Angular components. */
-    registry = input.required(...(ngDevMode ? [{ debugName: "registry" }] : /* istanbul ignore next */ []));
+    /**
+     * Component registry mapping catalog type names to Angular components.
+     * Required unless a {@link provideJsonRender} above supplies one.
+     */
+    registry = input(undefined, ...(ngDevMode ? [{ debugName: "registry" }] : /* istanbul ignore next */ []));
     /** Whether the spec is currently loading/streaming. */
     loading = input(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
     /** Fallback component for unknown types. */
@@ -2479,7 +2633,7 @@ class JsonRenderer {
      * The check is skipped while `loading` is true: a spec that is still
      * arriving is expected to reference children that have not streamed in yet.
      */
-    validate = input('off', ...(ngDevMode ? [{ debugName: "validate" }] : /* istanbul ignore next */ []));
+    validate = input(undefined, ...(ngDevMode ? [{ debugName: "validate" }] : /* istanbul ignore next */ []));
     /**
      * Caps on what the spec may cost the browser: `maxElements`, `maxDepth` and
      * `maxRepeatItems`. Unset by default, and each field is independently
@@ -2501,8 +2655,14 @@ class JsonRenderer {
      * `$bindState`, `$template`, a directive — has no value until render time,
      * so it is not checked.
      *
-     * Only read when `validate` is on, and — like the rest of the check —
-     * skipped while `loading`.
+     * The check is read only when `validate` is on, and — like the rest of
+     * it — skipped while `loading`.
+     *
+     * While `loading`, the catalog also gates mounting, whatever `validate` is:
+     * an element whose props do not yet pass its component's schema shows its
+     * registry entry's `fallback`, or nothing, instead of a component with half
+     * its props. Once an element has mounted it stays mounted, and when
+     * `loading` ends every element mounts.
      */
     catalog = input(null, ...(ngDevMode ? [{ debugName: "catalog" }] : /* istanbul ignore next */ []));
     /**
@@ -2530,33 +2690,52 @@ class JsonRenderer {
     stateStore;
     /** The action dispatcher of this renderer. */
     actions;
+    /**
+     * The nearest {@link provideJsonRender}'s defaults. Every option input
+     * falls through to these when left `null` or `undefined`; see
+     * {@link JsonRenderConfig} for the merge rules.
+     */
+    config = inject(JSON_RENDER_CONFIG, { optional: true }) ?? {};
+    mode = computed(() => this.validate() ?? this.config.validate ?? 'off', ...(ngDevMode ? [{ debugName: "mode" }] : /* istanbul ignore next */ []));
+    limits = computed(() => this.renderLimits() ?? this.config.renderLimits ?? null, ...(ngDevMode ? [{ debugName: "limits" }] : /* istanbul ignore next */ []));
+    specCatalog = computed(() => this.catalog() ?? this.config.catalog ?? null, ...(ngDevMode ? [{ debugName: "specCatalog" }] : /* istanbul ignore next */ []));
     /**
      * The spec as checked, and what the check found. While `loading`, the mode
      * is forced off: the spec is still arriving, and the missing children it
      * refers to are the normal state of a stream, not a defect.
      */
-    checked = computed(() => checkSpec(this.spec(), this.loading() ? 'off' : this.validate(), {
-        limits: this.renderLimits(),
-        catalog: this.catalog(),
+    checked = computed(() => checkSpec(this.spec(), this.loading() ? 'off' : this.mode(), {
+        limits: this.limits(),
+        catalog: this.specCatalog(),
     }), ...(ngDevMode ? [{ debugName: "checked" }] : /* istanbul ignore next */ []));
     constructor() {
         const root = inject(JsonRenderRootContext);
         // The fixed spec, not the input: a `visible` the check moved out of
         // `props` has to be the one the tree renders, or the fix is cosmetic.
         root.spec = computed(() => this.checked().spec, ...(ngDevMode ? [{ debugName: "spec" }] : /* istanbul ignore next */ []));
-        root.registry = this.registry;
+        const config = this.config;
+        // Read only once an element needs a component, like a required input:
+        // a renderer with no spec yet has no use for one.
+        root.registry = computed(() => {
+            const registry = this.registry() ?? config.registry;
+            if (!registry) {
+                throw new Error('[ngx-json-render] <json-render> has no registry. Bind [registry], or supply one for the whole app with provideJsonRender({ registry }).');
+            }
+            return registry;
+        }, ...(ngDevMode ? [{ debugName: "registry" }] : /* istanbul ignore next */ []));
         root.loading = this.loading;
-        root.fallback = this.fallback;
-        root.limits = this.renderLimits;
+        root.fallback = computed(() => this.fallback() ?? config.fallback ?? null, ...(ngDevMode ? [{ debugName: "fallback" }] : /* istanbul ignore next */ []));
+        root.limits = this.limits;
+        root.catalog = this.specCatalog;
         root.store = this.store;
         root.initialState = computed(() => this.state() ?? this.spec()?.state ?? {}, ...(ngDevMode ? [{ debugName: "initialState" }] : /* istanbul ignore next */ []));
-        root.handlers = this.handlers;
-        root.onAction = this.onAction;
-        root.navigate = this.navigate;
-        root.validationFunctions = this.validationFunctions;
-        root.functions = this.functions;
+        root.handlers = computed(() => mergeByName(config.handlers, this.handlers()), ...(ngDevMode ? [{ debugName: "handlers" }] : /* istanbul ignore next */ []));
+        root.onAction = computed(() => this.onAction() ?? config.onAction ?? null, ...(ngDevMode ? [{ debugName: "onAction" }] : /* istanbul ignore next */ []));
+        root.navigate = computed(() => this.navigate() ?? config.navigate ?? null, ...(ngDevMode ? [{ debugName: "navigate" }] : /* istanbul ignore next */ []));
+        root.validationFunctions = computed(() => mergeByName(config.validationFunctions, this.validationFunctions()), ...(ngDevMode ? [{ debugName: "validationFunctions" }] : /* istanbul ignore next */ []));
+        root.functions = computed(() => mergeByName(config.functions, this.functions()), ...(ngDevMode ? [{ debugName: "functions" }] : /* istanbul ignore next */ []));
         root.directiveRegistry = computed(() => {
-            const definitions = this.directives();
+            const definitions = mergeDirectives(config.directives, this.directives());
             return definitions ? createDirectiveRegistry(definitions) : undefined;
         }, ...(ngDevMode ? [{ debugName: "directiveRegistry" }] : /* istanbul ignore next */ []));
         root.emitStateChange = (changes) => this.stateChange.emit(changes);
@@ -2572,7 +2751,25 @@ class JsonRenderer {
         effect(() => {
             if (this.loading())
                 return;
-            reportSpecCheck(this.checked(), this.validate());
+            reportSpecCheck(this.checked(), this.mode());
+        });
+        // With validation off, a `root` that names no element renders nothing and
+        // nothing says why — the first mistake a hand-written spec tends to have.
+        // Skipped while loading (a stream sends `/root` before its element) and
+        // under `warn`/`strict`, where the check already reports `root_not_found`.
+        // Once per root key, not once per change detection run.
+        const warnedRoots = new Set();
+        effect(() => {
+            if (this.loading() || this.mode() !== 'off')
+                return;
+            const spec = this.checked().spec;
+            if (!spec?.root)
+                return;
+            const root = spec.root;
+            if (spec.elements?.[root] || warnedRoots.has(root))
+                return;
+            warnedRoots.add(root);
+            console.warn(`[ngx-json-render] root "${root}" is not in elements; nothing is rendered.`);
         });
     }
     rootKey = computed(() => {
@@ -2585,7 +2782,7 @@ class JsonRenderer {
         // A spec whose errors survived the fixes does not render under `strict`.
         // Reporting it and drawing half of it anyway is the behaviour the mode
         // exists to refuse.
-        if (this.validate() === 'strict' && checked.hasErrors)
+        if (this.mode() === 'strict' && checked.hasErrors)
             return null;
         const spec = checked.spec;
         return spec?.root && spec.elements?.[spec.root] ? spec.root : null;
@@ -2624,7 +2821,7 @@ class JsonRenderer {
         });
     }, ...(ngDevMode ? [{ debugName: "confirmInjector" }] : /* istanbul ignore next */ []));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JsonRenderer, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JsonRenderer, isStandalone: true, selector: "json-render", inputs: { spec: { classPropertyName: "spec", publicName: "spec", isSignal: true, isRequired: true, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null }, loading: { classPropertyName: "loading", publicName: "loading", isSignal: true, isRequired: false, transformFunction: null }, fallback: { classPropertyName: "fallback", publicName: "fallback", isSignal: true, isRequired: false, transformFunction: null }, validate: { classPropertyName: "validate", publicName: "validate", isSignal: true, isRequired: false, transformFunction: null }, renderLimits: { classPropertyName: "renderLimits", publicName: "renderLimits", isSignal: true, isRequired: false, transformFunction: null }, catalog: { classPropertyName: "catalog", publicName: "catalog", isSignal: true, isRequired: false, transformFunction: null }, state: { classPropertyName: "state", publicName: "state", isSignal: true, isRequired: false, transformFunction: null }, store: { classPropertyName: "store", publicName: "store", isSignal: true, isRequired: false, transformFunction: null }, handlers: { classPropertyName: "handlers", publicName: "handlers", isSignal: true, isRequired: false, transformFunction: null }, onAction: { classPropertyName: "onAction", publicName: "onAction", isSignal: true, isRequired: false, transformFunction: null }, navigate: { classPropertyName: "navigate", publicName: "navigate", isSignal: true, isRequired: false, transformFunction: null }, validationFunctions: { classPropertyName: "validationFunctions", publicName: "validationFunctions", isSignal: true, isRequired: false, transformFunction: null }, functions: { classPropertyName: "functions", publicName: "functions", isSignal: true, isRequired: false, transformFunction: null }, directives: { classPropertyName: "directives", publicName: "directives", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { stateChange: "stateChange" }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JsonRenderer, isStandalone: true, selector: "json-render", inputs: { spec: { classPropertyName: "spec", publicName: "spec", isSignal: true, isRequired: true, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: false, transformFunction: null }, loading: { classPropertyName: "loading", publicName: "loading", isSignal: true, isRequired: false, transformFunction: null }, fallback: { classPropertyName: "fallback", publicName: "fallback", isSignal: true, isRequired: false, transformFunction: null }, validate: { classPropertyName: "validate", publicName: "validate", isSignal: true, isRequired: false, transformFunction: null }, renderLimits: { classPropertyName: "renderLimits", publicName: "renderLimits", isSignal: true, isRequired: false, transformFunction: null }, catalog: { classPropertyName: "catalog", publicName: "catalog", isSignal: true, isRequired: false, transformFunction: null }, state: { classPropertyName: "state", publicName: "state", isSignal: true, isRequired: false, transformFunction: null }, store: { classPropertyName: "store", publicName: "store", isSignal: true, isRequired: false, transformFunction: null }, handlers: { classPropertyName: "handlers", publicName: "handlers", isSignal: true, isRequired: false, transformFunction: null }, onAction: { classPropertyName: "onAction", publicName: "onAction", isSignal: true, isRequired: false, transformFunction: null }, navigate: { classPropertyName: "navigate", publicName: "navigate", isSignal: true, isRequired: false, transformFunction: null }, validationFunctions: { classPropertyName: "validationFunctions", publicName: "validationFunctions", isSignal: true, isRequired: false, transformFunction: null }, functions: { classPropertyName: "functions", publicName: "functions", isSignal: true, isRequired: false, transformFunction: null }, directives: { classPropertyName: "directives", publicName: "directives", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { stateChange: "stateChange" }, providers: [
             JsonRenderRootContext,
             JsonRenderStateService,
             JsonRenderValidationService,
@@ -2673,7 +2870,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
       }
     }
   `, styles: [":host{display:contents}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { spec: [{ type: i0.Input, args: [{ isSignal: true, alias: "spec", required: true }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], loading: [{ type: i0.Input, args: [{ isSignal: true, alias: "loading", required: false }] }], fallback: [{ type: i0.Input, args: [{ isSignal: true, alias: "fallback", required: false }] }], validate: [{ type: i0.Input, args: [{ isSignal: true, alias: "validate", required: false }] }], renderLimits: [{ type: i0.Input, args: [{ isSignal: true, alias: "renderLimits", required: false }] }], catalog: [{ type: i0.Input, args: [{ isSignal: true, alias: "catalog", required: false }] }], state: [{ type: i0.Input, args: [{ isSignal: true, alias: "state", required: false }] }], store: [{ type: i0.Input, args: [{ isSignal: true, alias: "store", required: false }] }], handlers: [{ type: i0.Input, args: [{ isSignal: true, alias: "handlers", required: false }] }], onAction: [{ type: i0.Input, args: [{ isSignal: true, alias: "onAction", required: false }] }], navigate: [{ type: i0.Input, args: [{ isSignal: true, alias: "navigate", required: false }] }], validationFunctions: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationFunctions", required: false }] }], functions: [{ type: i0.Input, args: [{ isSignal: true, alias: "functions", required: false }] }], directives: [{ type: i0.Input, args: [{ isSignal: true, alias: "directives", required: false }] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }] } });
+        }], ctorParameters: () => [], propDecorators: { spec: [{ type: i0.Input, args: [{ isSignal: true, alias: "spec", required: true }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: false }] }], loading: [{ type: i0.Input, args: [{ isSignal: true, alias: "loading", required: false }] }], fallback: [{ type: i0.Input, args: [{ isSignal: true, alias: "fallback", required: false }] }], validate: [{ type: i0.Input, args: [{ isSignal: true, alias: "validate", required: false }] }], renderLimits: [{ type: i0.Input, args: [{ isSignal: true, alias: "renderLimits", required: false }] }], catalog: [{ type: i0.Input, args: [{ isSignal: true, alias: "catalog", required: false }] }], state: [{ type: i0.Input, args: [{ isSignal: true, alias: "state", required: false }] }], store: [{ type: i0.Input, args: [{ isSignal: true, alias: "store", required: false }] }], handlers: [{ type: i0.Input, args: [{ isSignal: true, alias: "handlers", required: false }] }], onAction: [{ type: i0.Input, args: [{ isSignal: true, alias: "onAction", required: false }] }], navigate: [{ type: i0.Input, args: [{ isSignal: true, alias: "navigate", required: false }] }], validationFunctions: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationFunctions", required: false }] }], functions: [{ type: i0.Input, args: [{ isSignal: true, alias: "functions", required: false }] }], directives: [{ type: i0.Input, args: [{ isSignal: true, alias: "directives", required: false }] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }] } });
 
 /**
  * Provides the repeat scope (item, index, absolute base path) to the elements
@@ -2878,8 +3075,13 @@ function defineRegistry(catalog, options) {
     // Build the component registry, attaching slot metadata from the catalog.
     const registry = {};
     if (options.components) {
-        for (const [name, component] of Object.entries(options.components)) {
-            const entry = { component };
+        for (const [name, value] of Object.entries(options.components)) {
+            const entry = typeof value === 'function'
+                ? { component: value }
+                : {
+                    component: value.component,
+                    ...(value.fallback ? { fallback: value.fallback } : {}),
+                };
             const slots = catalogComponents?.[name]?.slots;
             if (slots)
                 entry.slots = slots;
@@ -3809,5 +4011,5 @@ function injectChatUI(options) {
  * Generated bundle index. Do not edit.
  */
 
-export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, ɵregisterStreamObserver };
+export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JSON_RENDER_CONFIG, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, provideJsonRender, ɵregisterStreamObserver };
 //# sourceMappingURL=ngx-json-render.mjs.map