@xmachines/play-dom 6.1.0 → 7.0.0

package/dist/PlayRenderer.js

@@ -1,689 +1,594 @@
-/**
- * PlayRenderer.ts — the XMachines wrapper of @xmachines/json-render-dom.
- *
- * It connects actor.currentView, an atom, to the DOM renderer below it, with
- * watchAtom. It gives you the connect() method and the disconnect() method, in
- * the same pattern as the PlayRenderer class of play-react, of play-vue, and of
- * play-solid.
- *
- * The state store: the renderer uses the external `store` option when the caller
- * gives one, and this is the controlled mode. Without that option, it makes a new
- * @xstate/store atom for each view transition, with the values of spec.state.
- */
-import { createAtom, watchAtom } from "@xmachines/play-atom";
+import { createAtom } from "@xmachines/play-atom";
 import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
-import { createReportGuard, createViewStoreLifecycle, refreshContextSubtree, } from "@xmachines/play-view";
+import { bindStoreHandlers, createReportGuard, createViewSession, forwardRenderError } from "@xmachines/play-view";
 import { releaseQuietly } from "@xmachines/core/utils";
 import { createIncrementalRenderer } from "@xmachines/json-render-dom";
+//#region packages/play-dom/src/PlayRenderer.ts
+/**
+* PlayRenderer.ts — the XMachines wrapper of @xmachines/json-render-dom.
+*
+* It connects actor.currentView, an atom, to the DOM renderer below it, through the
+* view session of @xmachines/play-view. It gives you the connect() method and the disconnect() method, in
+* the same pattern as the PlayRenderer class of play-react, of play-vue, and of
+* play-solid.
+*
+* The state store: the renderer uses the external `store` option when the caller
+* gives one, and this is the controlled mode. Without that option, it makes a new
+* @xstate/store atom for each view transition, with the values of spec.state.
+*/
 /**
- * What the report guard writes, and what it lets through.
- *
- * It CONTAINS a handler of the host that throws, exactly as the four framework renderers
- * do. The five hold one rule, and a caller learns it one time: a handler of the host never
- * defeats the containment. A host that must escalate raises the failure from a task of its
- * own, which reaches the global handler of the page in every one of the five.
- *
- * It stands ABOVE the doc comment of the class, and so does every other declaration of
- * this module: a declaration takes the comment block that stands directly before it, so a
- * const or a function placed between that comment and the class takes the documentation
- * of `PlayRenderer` with it, and the class reaches the generated reference with none.
- */
-const GUARD_MESSAGES = {
-    noHandler: "[@xmachines/play-dom] PlayRenderer contained a failed rebuild of the view. " +
-        "Give an onError option to receive it.",
-    handlerThrew: "[@xmachines/play-dom] the onError handler of the host threw. " +
-        "PlayRenderer contained the failure of the view all the same.",
+* What the report guard writes, and what it lets through.
+*
+* It CONTAINS a handler of the host that throws, exactly as the four framework renderers
+* do. The five hold one rule, and a caller learns it one time: a handler of the host never
+* defeats the containment. A host that must escalate raises the failure from a task of its
+* own, which reaches the global handler of the page in every one of the five.
+*
+* It stands ABOVE the doc comment of the class, and so does every other declaration of
+* this module: a declaration takes the comment block that stands directly before it, so a
+* const or a function placed between that comment and the class takes the documentation
+* of `PlayRenderer` with it, and the class reaches the generated reference with none.
+*/
+var GUARD_MESSAGES = {
+	noHandler: "[@xmachines/play-dom] PlayRenderer contained a failed rebuild of the view. Give an onError option to receive it.",
+	handlerThrew: "[@xmachines/play-dom] the onError handler of the host threw. PlayRenderer contained the failure of the view all the same."
 };
 /**
- * Reports a failure of one release of a caller, for `releaseQuietly` of `@xmachines/core/utils`.
- *
- * Every release that `disconnect()`, `render()`, and `resetFailedRebuild()` run is CODE
- * OF A CALLER: the `unsubscribe` of a store that the host gave, and the watch cleanups
- * that the inner renderer registered. Each one can throw, and a throw must stop no path.
- * `render()` releases the registrations of the previous view on the path of a view that
- * works, and the comment at that call gives its reason.
- *
- * `resetFailedRebuild()` runs the releases of a FAILED rebuild, BEFORE the renderer
- * contains the failure of the view. A throw there takes the containment down with it: the
- * catch that called it reaches `contain()` never, so the failure of the view reaches no
- * handler, the dead tree stays on the screen, and the failure of the release escapes in
- * its place — which is both outcomes that the containment exists to prevent.
- *
- * `disconnect()` has no containment to defeat, and it has the same rule for a second
- * reason: a throw from the first release skips every release after it, it skips the clear
- * of the container, and it skips the reset of the identity. The renderer then holds a
- * half teardown that no caller can complete.
- *
- * Each release therefore stands alone, and a failure of one goes to `console.error`.
- */
+* Reports a failure of one release of a caller, for `releaseQuietly` of `@xmachines/core/utils`.
+*
+* Every release that `disconnect()`, `render()`, and `resetFailedRebuild()` run is CODE
+* OF A CALLER: the `unsubscribe` of a store that the host gave, and the watch cleanups
+* that the inner renderer registered. Each one can throw, and a throw must stop no path.
+* `render()` releases the registrations of the previous view on the path of a view that
+* works, and the comment at that call gives its reason.
+*
+* `resetFailedRebuild()` runs the releases of a FAILED rebuild, BEFORE the renderer
+* contains the failure of the view. A throw there takes the containment down with it: the
+* catch that called it reaches `contain()` never, so the failure of the view reaches no
+* handler, the dead tree stays on the screen, and the failure of the release escapes in
+* its place — which is both outcomes that the containment exists to prevent.
+*
+* `disconnect()` has no containment to defeat, and it has the same rule for a second
+* reason: a throw from the first release skips every release after it, it skips the clear
+* of the container, and it skips the reset of the identity. The renderer then holds a
+* half teardown that no caller can complete.
+*
+* Each release therefore stands alone, and a failure of one goes to `console.error`.
+*/
 function reportReleaseFailure(releaseFailure) {
-    console.error("[@xmachines/play-dom] a release of PlayRenderer threw. " +
-        "The renderer completed the teardown all the same.", releaseFailure);
+	console.error("[@xmachines/play-dom] a release of PlayRenderer threw. The renderer completed the teardown all the same.", releaseFailure);
 }
 /**
- * PlayRenderer connects the `currentView` atom of an actor to the DOM renderer.
- *
- * It watches `actor.currentView` through the atoms. It renders each
- * `DomComponentRenderer` function into `container` on every view transition.
- * `disconnect()` clears the container.
- *
- * Every option of `PlayDomOptions`, which extends `UIProviderOptions`, goes into
- * `DomRenderContext` on each render pass:
- * - `functions` — the named compute functions of a `{ $computed: "name" }` prop expression
- * - `directives` — your own dynamic values with a `$` prefix, from `defineDirective`. The renderer resolves them with the props
- * - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`
- * - `navigate` — the navigation callback. The renderer calls it for an `onSuccess: { navigate: "..." }` action binding
- * - `onRenderError` — the renderer calls it with `(error, name)` for a component render error and for an action handler rejection
- *
- * **The preferred use, with `registryResult`:**
- * ```typescript
- * import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
- *
- * const registryResult = defineRegistry(catalog, { components, actions });
- * const renderer = new PlayRenderer(container, actor, registryResult.registry, {
- *   registryResult, // it connects setState and getState of the xstate store for you
- *   navigate: (path) => myRouter.push(path),
- *   functions: { fullName: (args) => `${args.first} ${args.last}` },
- * });
- * renderer.connect();
- * // Later:
- * renderer.disconnect();
- * ```
- *
- * **The controlled store mode** — you give your own `StateStore`:
- * ```typescript
- * import { createAtom } from "@xmachines/play-atom";
- * import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
- *
- * const atom  = createAtom({ username: "" });
- * const store = xstateStoreStateStore({ atom });
- * const renderer = new PlayRenderer(container, actor, registry, { registryResult, store });
- * renderer.connect();
- * ```
- *
- * A second `connect()` is safe. A `connect()` call on a connected renderer
- * disconnects it first. Therefore the renderer holds no second render
- * subscription.
- */
-export class PlayRenderer {
-    container;
-    actor;
-    registry;
-    options;
-    /**
-     * True from the start of `connect()` to the end of `disconnect()`.
-     *
-     * The watcher cannot answer this question. `connect()` installs it AFTER the
-     * synchronous first render, so a host that calls `connect()` again from the `onError`
-     * of that render finds no watcher, and a test of the watcher alone would skip the
-     * `disconnect()` and leave the guard of the abandoned connection alive for ever.
-     */
-    connected = false;
-    unwatch = null;
-    storeUnsubscribe = null;
-    /**
-     * The cleanup functions of the live watch subscriptions. This field is a `Set`,
-     * and not an array, so that each registered cleanup function can delete ITSELF on
-     * its call: the incremental renderer releases a watcher when its element unmounts,
-     * and it calls the registered wrapper. The Set therefore shrinks with the live
-     * subscriptions. It does not collect one spent closure for each historical mount of
-     * a view with a long life.
-     */
-    watchCleanups = new Set();
-    /**
-     * The viewKey of the view on the screen now, and the store behind it, without the
-     * guard. An emission with the same key means that only the /context projection
-     * moved: the fast path for a slice in render() refreshes the store in place, and it
-     * does not remove the tree. The ephemeral view state, such as a draft or a toggle,
-     * therefore stays. A null emission, from a state with no meta.view, is a GAP, and
-     * not a new view: the DOM goes away, but the identity and the store stay. A return
-     * to the same view therefore builds again around the ephemeral state that survived,
-     * in the same way as the framework providers. `disconnect()` resets both fields,
-     * because a store that stays alive must not outlive the connection.
-     */
-    lastViewKey = undefined;
-    currentStore = null;
-    /**
-     * The incremental renderer of the live tree, and the `root` and `elements` of the
-     * spec that it renders. An emission with the same viewKey and the same two
-     * references moved the /context projection alone. An emission with the same
-     * viewKey and a new `elements` object is a new spec of the same view — a composed
-     * view whose page changed, or a streamed chunk — and the renderer takes it in place
-     * through `setSpec`.
-     */
-    incremental = null;
-    lastRoot = undefined;
-    lastElements = undefined;
-    /** The fallback element, built at the first moment that the renderer shows it. */
-    fallbackElement = null;
-    /**
-     * The shared coordinator of the store lifecycle, from @xmachines/play-view. It
-     * seeds the store again on a change of the viewKey, it refreshes /context in place
-     * in every other case, and it guards the identity cache. The two fields above,
-     * lastViewKey and currentStore, stay as the DOM-side record for the fast path of a
-     * slice. That path is about the live TREE, which is the spec and the subscription,
-     * and not about the store.
-     */
-    storeLifecycle = createViewStoreLifecycle((seed) => xstateStoreStateStore({ atom: createAtom(seed) }));
-    /**
-     * `disconnect()` sets this field to `false` before it calls `storeUnsub()`.
-     * The `rerender` closure reads the flag at its start. Therefore a synchronous
-     * callback from the `StateStore` implementation inside its own `unsubscribe()`
-     * call, which is rare but correct, changes no detached DOM tree.
-     */
-    alive = true;
-    /**
-     * The report guard, from @xmachines/play-view.
-     *
-     * It blocks a reset that the host calls from INSIDE the report, and every reset once
-     * the renderer is disconnected. The five renderers share the one implementation.
-     *
-     * `alive` cannot answer the second half. A contained failure sets that flag to `false`
-     * and the next emission sets it back, because it guards the callback of the store
-     * subscription — a reset that a host keeps outlives both.
-     */
-    // It is NOT readonly: `disconnect()` disposes the guard, and `connect()` revives the
-    // renderer, so a reconnected renderer needs a guard that is not spent.
-    guard = createReportGuard(GUARD_MESSAGES);
-    /**
-     * The retry that every report of THIS connection hands the host.
-     *
-     * `connect()` builds one, beside the guard that it belongs to. The four framework
-     * renderers hand the host one reset for the life of the provider, and this field holds
-     * the same rule for the life of the connection.
-     */
-    retry = this.retryOf(this.guard);
-    /**
-     * @param container - The `HTMLElement` to render into. Each view transition clears it and fills it again.
-     * @param actor     - The actor with the `currentView` atom. It must implement `Viewable`.
-     * @param registry  - The map of the component renderers, usually `registryResult.registry` from `defineRegistry`.
-     * @param options   - The configuration. See {@link PlayDomOptions}:
-     *   - `registryResult`      — it connects `setState` and `state` of the xstate store for you.
-     *   - `store`               — an external `StateStore`, which is the controlled mode. It replaces the values of `spec.state`.
-     *   - `loading`             — the flag of the streaming mode. It stops each warning about an absent child.
-     *   - `functions`           — the named compute functions of a `$computed` prop expression.
-     *   - `directives`          — your own dynamic values with a `$` prefix. The renderer resolves them with the props.
-     *   - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`.
-     *   - `navigate`            — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`.
-     *   - `onRenderError`       — the `(error, name)` handler of a component render error and of an action handler rejection. It stops the `console.error` fallback.
-     *   - `onError`             — the `(error, reset)` handler of a failure of a complete rebuild. The renderer contains such a failure always, and this option says where the report goes.
-     *   - `fallback`            — the element to show for every null view, and after a contained failure.
-     */
-    constructor(container, actor, registry, options = {}) {
-        this.container = container;
-        this.actor = actor;
-        this.registry = registry;
-        this.options = options;
-    }
-    /**
-     * Starts the watch of actor.currentView, and renders into the container.
-     * It renders the first view synchronously, then it subscribes to the atom changes.
-     *
-     * A `connect()` call on a connected renderer, where a `disconnect()` call did not
-     * follow the previous `connect()`, installs a second `watchAtom` subscription.
-     * Each view change then renders two times. Therefore this method disconnects the
-     * renderer first.
-     */
-    connect() {
-        if (this.connected)
-            this.disconnect();
-        this.connected = true;
-        const guard = createReportGuard(GUARD_MESSAGES);
-        this.guard = guard;
-        // ONE retry for the connection, as the four framework renderers hand the host one
-        // reset for the life of the provider. A retry built for each report gives a host
-        // that keys a Map on the callback one entry for each failure.
-        this.retry = this.retryOf(guard);
-        // The first render is SYNCHRONOUS, and it can reach `onError`. It needs no `try`: the
-        // renderer contains a failed rebuild, and the guard contains a handler of the host
-        // that throws, so this call returns for every view that a caller can give.
-        const seeded = this.actor.currentView.get();
-        this.render(seeded);
-        // A host that tears the renderer down from the handler — a fatal view, and the host
-        // gives up — calls `disconnect()` while this method still runs, and the line below
-        // would then hand the renderer a live watcher again: it renders into a container
-        // that the host released, and the watcher outlives the actor.
-        //
-        // A host that CONNECTS again from the handler reaches the same line. The `connected`
-        // flag above makes that call disconnect this connection first, so both hosts dispose
-        // the guard of THIS call. Ask that guard, and not the field: the field holds the
-        // guard of the connection that took the place of this one.
-        if (guard.blocked())
-            return;
-        this.unwatch = watchAtom(this.actor.currentView, (view) => {
-            this.render(view);
-        });
-        // The actor can hold ANOTHER view already. The render above is synchronous, and a
-        // host that REPAIRS the actor from the handler — a bad initial view, and the host
-        // sends a recovery event — moves the atom between the read and the line above.
-        // `watchAtom` seeds nothing, so the repaired view would wait for the next
-        // emission of the actor, and a screen that shows the fallback of a failure that the
-        // host repaired already would wait with it. Render the view that the actor holds
-        // NOW.
-        //
-        // This runs one time, and it loops for no host: a repair from THIS render reaches
-        // the watcher above, which is installed already.
-        const current = this.actor.currentView.get();
-        if (current !== seeded)
-            this.render(current);
-    }
-    /**
-     * Stops the watch and clears the container.
-     */
-    disconnect() {
-        this.connected = false;
-        this.guard.dispose();
-        releaseQuietly(this.unwatch, reportReleaseFailure);
-        this.unwatch = null;
-        // Set the refs to null first. A rerender callback that is still in flight therefore
-        // sees null, and it stops.
-        // Capture each array and each function before the code clears them. Therefore the
-        // code calls the correct cleanup functions, also when the cancellation of the store
-        // subscription starts a synchronous rerender. Without the capture, that rerender
-        // overwrites watchCleanups before the loop over them.
-        const storeUnsub = this.storeUnsubscribe;
-        const watchCleanups = [...this.watchCleanups];
-        this.storeUnsubscribe = null;
-        this.watchCleanups = new Set();
-        // Set alive = false before the storeUnsub() call. A synchronous rerender callback
-        // from inside unsubscribe() therefore returns at once.
-        this.alive = false;
-        // See reportReleaseFailure: a throw of one release must skip none of the work below it.
-        releaseQuietly(storeUnsub, reportReleaseFailure);
-        for (const cleanup of watchCleanups)
-            releaseQuietly(cleanup, reportReleaseFailure);
-        this.container.replaceChildren();
-        // The rule of the lifetime: the store that stays alive dies with the connection.
-        this.lastViewKey = undefined;
-        this.currentStore = null;
-        this.incremental = null;
-        this.lastRoot = undefined;
-        this.lastElements = undefined;
-        this.storeLifecycle.reset();
-    }
-    /**
-     * The number of live watch-subscription cleanup functions now.
-     *
-     * @internal This accessor is for a test only. A test asserts with it that the
-     * collection of the watch cleanups holds the live registrations, and that no mount
-     * leaks. It is not part of the public API, and it can change without a notice.
-     */
-    get watchCleanupCount() {
-        return this.watchCleanups.size;
-    }
-    render(view) {
-        // ── The fast path of a slice ────────────────────────────────────────────
-        // The viewKey of the live tree is the same → only the /context projection changed.
-        // deriveCurrentView uses the selected meta entry as the key of each emission, and the
-        // authored spec of a state is static. Refresh the subtree of the store in place: the
-        // store subscription below calls incremental.update() already, and that function
-        // compares the snapshots and patches the elements of the change only. Skip the
-        // teardown completely, so that the ephemeral view state stays.
-        // createIncrementalRenderer binds the SPEC at its construction. Therefore this path
-        // is safe only because the spec is the same. A real view change, which means a
-        // different viewKey or no viewKey for a comparison, still rebuilds the tree below, as
-        // the discard-on-view-transition contract of the incremental renderer says.
-        if (view !== null &&
-            view.viewKey !== undefined &&
-            this.lastViewKey === view.viewKey &&
-            this.currentStore !== null &&
-            this.storeUnsubscribe !== null) {
-            // The fast path reads `spec.state` too, so it fails exactly as a rebuild does.
-            // It sat OUTSIDE the try below, so a stream that keeps its viewKey and emits a
-            // spec with an accessor that throws escaped the callback of watchAtom
-            // uncontained, with the stale tree still on the screen.
-            try {
-                if (view.root === this.lastRoot && view.elements === this.lastElements) {
-                    refreshContextSubtree(this.currentStore, view);
-                }
-                else {
-                    // The lifecycle refreshes /context, and it seeds the authored state of the
-                    // views that a composed view shows for the first time. The store update
-                    // reaches the incremental renderer first, on the spec that it holds, and
-                    // setSpec then renders the new spec against the store of NOW.
-                    this.storeLifecycle.resolve(this.actor, view, this.options.store);
-                    this.incremental?.setSpec(view);
-                    this.lastRoot = view.root;
-                    this.lastElements = view.elements;
-                }
-            }
-            catch (error) {
-                this.failView(error);
-            }
-            return;
-        }
-        this.alive = true;
-        // Capture the values and clear them before the call. Some store implementations
-        // fire a synchronous callback during their unsubscribe(). Without this order, that
-        // callback sees a live storeUnsubscribe, and it enters the rerender path again with
-        // an old view and an old store.
-        // disconnect() uses the same capture-then-clear pattern.
-        // See reportReleaseFailure. This release is code of a caller, and it runs on the path of a
-        // view that WORKS: a throw here would abort the render of a good view, and it would
-        // leave the renderer with the tree of the previous view on the screen and half of
-        // its registrations released.
-        const oldUnsub = this.storeUnsubscribe;
-        this.storeUnsubscribe = null;
-        releaseQuietly(oldUnsub, reportReleaseFailure);
-        // Release the watch cleanups of the first render of the previous view.
-        // Without this step, the watch subscriptions of the previous view stay active between
-        // a view transition and the first store update of the new view. They then hold a
-        // reference to a DOM element that is gone, and the garbage collector cannot take
-        // it.
-        const prevWatchCleanups = [...this.watchCleanups];
-        this.watchCleanups = new Set();
-        for (const cleanup of prevWatchCleanups)
-            releaseQuietly(cleanup, reportReleaseFailure);
-        this.container.replaceChildren();
-        // A null emission is a gap between two views, and not a new view: keep lastViewKey
-        // and currentStore. A return to the same identity therefore uses the store below
-        // again. disconnect() stays the boundary of the lifetime.
-        if (!view) {
-            // Show the fallback for EVERY null view, and not for the first mount only. The
-            // four framework providers hold the same rule: a null currentView renders the
-            // placeholder content of the provider, at any moment of the life of the tree.
-            this.showFallback();
-            return;
-        }
-        // Resolve the store through the shared lifecycle. There are three results: the
-        // external store, which is the controlled mode, and the coordinator refreshes its
-        // /context, because the machinery owns /context in both modes; the store that the
-        // coordinator kept, when this emission returns to the live identity (a view, then
-        // null, then the same view — the fast path could not take this case, because the DOM
-        // is gone, and the coordinator refreshes /context in place, because the context can
-        // move during the gap); or a new store of this view, with the values of the composed
-        // state.
-        // The resolution stands INSIDE the try. It reads `spec.state`, and a spec can fail
-        // there — the accessor of a projection throws, or a seed of the store does. Such a
-        // failure aborts the rebuild exactly as a failure of renderView does, so the
-        // containment must cover it. The ErrorBoundary of play-solid covers the same
-        // accessor, and packages/play-solid/test/PlayRenderer-edge-error-boundary.test.tsx
-        // holds that rule.
-        try {
-            const resolution = this.storeLifecycle.resolve(this.actor, view, this.options.store);
-            this.lastViewKey = view.viewKey;
-            // The code keeps the store without a guard, for the refresh of the fast path of a slice.
-            this.currentStore = resolution.store;
-            this.renderView(view, resolution.guardedStore);
-        }
-        catch (error) {
-            // Containment: the renderer holds a failure of the complete rebuild ALWAYS. It
-            // propagates none — not out of connect() for the initial view, and not out of
-            // the callback of watchAtom for a later view. No option turns this on, and
-            // none turns it off.
-            // failView() clears the container and fills it with the fallback, exactly as on
-            // a null view. The next view that renders clears the container again, which
-            // removes the fallback.
-            this.failView(error);
-        }
-    }
-    /**
-     * The end of a render that failed, in ONE place.
-     *
-     * Three paths render — the fast path of a slice, the complete rebuild, and the write
-     * of the store — and each one ends here. The ORDER is load-bearing: the reset takes
-     * the registrations of the dead tree down BEFORE the report, so a handler of the host
-     * that renders again meets a renderer that holds nothing of the failed attempt. A
-     * second copy of the pair is a second chance to put the two in the other order.
-     *
-     * @param error - The failure that the renderer contains.
-     */
-    failView(error) {
-        this.resetFailedRebuild();
-        this.contain(error);
-    }
-    /**
-     * Clears the screen of the failed view, shows the fallback, and reports the failure.
-     *
-     * The renderer contains such a failure ALWAYS. No option turns the containment on,
-     * and none turns it off: `onError` says where the report goes, and `fallback` says
-     * what the empty container shows. The four framework renderers hold the same rule,
-     * because an error boundary of a framework is not an option that a caller turns off.
-     * A host that must escalate a failure raises it from a task of its own —
-     * `rethrowLater(error)` of `@xmachines/core/utils` — because the guard contains a handler
-     * that throws, exactly as the four framework renderers do.
-     *
-     * The container is cleared FIRST. The fast path of a slice holds the live tree of the
-     * previous emission, and that tree is dead as soon as the refresh throws, so the
-     * renderer must not keep it on the screen. A clear container also lets the fallback
-     * stand alone.
-     *
-     * The SCREEN comes first, and the report second: a handler that throws — a reporter
-     * that fails, or one that re-raises to escalate — must not defeat the containment
-     * that it was given to observe. With the order reversed the container stays empty AND
-     * the error escapes, which is both outcomes that the containment exists to prevent.
-     */
-    contain(error) {
-        this.container.replaceChildren();
-        this.showFallback();
-        // Without `onError` the error reaches no handler and no caller. Write it to
-        // `console.error`, in the same way as the inner renderer does for a component that
-        // throws without an `onRenderError` handler. A silent crash is the one result that
-        // no caller can debug.
-        const { onError } = this.options;
-        // The guard and the retry of THIS connection, read one time. A `connect()` that the
-        // handler starts replaces both fields, and this report belongs to the connection
-        // that reported.
-        const guard = this.guard;
-        const retry = this.retry;
-        guard.report(error, onError && (() => onError(error, retry)));
-    }
-    /**
-     * Builds the retry that one report hands the host.
-     *
-     * The read of the atom happens at the moment of the CALL: a retry that held the view
-     * that failed would take a host off the healthy screen and back onto the one that
-     * threw.
-     *
-     * The retry belongs to the guard of ITS connection, and it asks that guard alone. A
-     * host may KEEP the callback — a "Retry" button of a toast outlives the route that
-     * opened it — and `disconnect()` disposes the guard that was live then. `connect()`
-     * disconnects a connected renderer first, so every guard that leaves the field is a
-     * disposed guard, and a retry of an older connection stays dead. The rule of the prop
-     * is one rule: a reset after `disconnect()` does nothing.
-     *
-     * @param guard - The guard of the connection that this retry belongs to.
-     */
-    retryOf(guard) {
-        return () => {
-            if (guard.blocked())
-                return;
-            this.render(this.actor.currentView.get());
-        };
-    }
-    /**
-     * Appends the fallback element to the container, which the caller cleared already.
-     * The renderer calls it for a null view, and after a failure of a rebuild that it
-     * contains. Both callers clear the container first. `appendChild` moves the node.
-     * Therefore a second call adds no copy.
-     */
-    showFallback() {
-        const fallback = this.options.fallback;
-        if (fallback == null)
-            return;
-        // The producer of the fallback is CODE OF THE HOST, and it can throw: a template
-        // lookup that finds nothing, a DOM API that the runtime lacks. This method runs on
-        // the null path outside every try, and inside `contain()` after the containment
-        // decided to hold an error — so a throw here escaped `connect()` and the callback
-        // of watchAtom uncontained, and it turned a contained failure into an uncontained
-        // one with the container empty.
-        //
-        // The report goes to `console.error` and NOT to `onError`: this method runs from
-        // inside `contain()`, and a second trip through the containment would report the
-        // failure of the fallback as a failure of the view.
-        try {
-            // A producer runs at the first moment that the renderer needs the element, and
-            // the memo keeps it: a later null view of THIS renderer shows the same node, and
-            // a renderer whose view is never null builds nothing at all.
-            this.fallbackElement ??= typeof fallback === "function" ? fallback() : fallback;
-            this.container.appendChild(this.fallbackElement);
-        }
-        catch (error) {
-            console.error("[@xmachines/play-dom] the fallback of PlayRenderer failed to build. " +
-                "The container stays empty.", error);
-        }
-    }
-    /**
-     * A rebuild that fails must not leave the guard of the fast path armed on a dead
-     * tree, because the container is empty already. Therefore this code resets the view
-     * identity. The next emission, also one with the same viewKey, then makes a
-     * complete render again. It does not patch a store that nothing shows.
-     *
-     * It releases the watch subscriptions of the dead tree too. A complete rebuild
-     * releases them before it builds again, and disconnect() releases them at the end of
-     * the life of the renderer — but a failure takes the DOM down HERE, between those two
-     * moments. Without this step one update of the store of the host runs every watch
-     * action of a tree that nothing shows, against detached elements, with `send` still
-     * bound to the actor. The fast path of a slice leaves a live tree of its own, and it
-     * reaches this code only when it fails.
-     */
-    resetFailedRebuild() {
-        // Capture both, clear both, and set alive = false BEFORE the unsubscribe — the
-        // order of disconnect(). Some StateStore implementations fire a synchronous
-        // callback from inside their own unsubscribe(). Without the flag that callback
-        // passes the guard and runs incremental.update() on the tree that this method is
-        // taking down, with `send` still bound to the actor; without the capture it also
-        // overwrites watchCleanups before the loop below reaches it. render() sets the
-        // flag to true again on the complete rebuild that the next emission makes, and the
-        // fast path of a slice needs storeUnsubscribe, which is null from here.
-        const failedUnsub = this.storeUnsubscribe;
-        const failedWatchCleanups = [...this.watchCleanups];
-        this.storeUnsubscribe = null;
-        this.watchCleanups = new Set();
-        this.alive = false;
-        // See reportReleaseFailure. This method runs BEFORE contain(), so a throw here would take
-        // the place of the failure of the view that the renderer contains.
-        releaseQuietly(failedUnsub, reportReleaseFailure);
-        for (const cleanup of failedWatchCleanups)
-            releaseQuietly(cleanup, reportReleaseFailure);
-        this.lastViewKey = undefined;
-        this.currentStore = null;
-        this.incremental = null;
-        this.lastRoot = undefined;
-        this.lastElements = undefined;
-        this.storeLifecycle.reset();
-    }
-    /**
-     * The tail of a complete rebuild, which can throw. See the catch block of render().
-     *
-     * @param guardedStore - Everything that the spec can write through, which includes
-     *   $bindState, setState, and a chained set, receives the GUARDED store: /context is
-     *   read-only to the spec, because the machine context changes through an event
-     *   only.
-     */
-    renderView(view, guardedStore) {
-        const send = this.actor.send.bind(this.actor);
-        // Build a SetState function on the xstate store.
-        // The code calls it late, at the moment of an action, and not at the moment of the
-        // handlers() call. Therefore each action sees the newest state of the store.
-        const setState = (updater) => {
-            const prev = guardedStore.getSnapshot();
-            const next = updater(prev);
-            // The code calls store.update() with a complete snapshot of the state, and not with
-            // a map of a patch. This works with createStoreAdapter and with createStateStore,
-            // where update() merges the given top-level keys in a shallow way, and therefore
-            // replaces the complete model of the state. Change this call to a patch with a path
-            // as its key only after a change of the StateStore contract.
-            // The store with the guard lets the context key of this read-modify-write round trip
-            // pass, because the code touches that key not. A real mutation of /context
-            // throws.
-            guardedStore.update(next);
-        };
-        // Resolve the handlers from registryResult. This connects setState and getState of the store.
-        const handlers = this.options.registryResult
-            ? this.options.registryResult.handlers(() => setState, () => guardedStore.getSnapshot())
-            : {};
-        const loading = this.options.loading;
-        const functions = this.options.functions;
-        const directives = this.options.directives;
-        const validationFunctions = this.options.validationFunctions;
-        const navigate = this.options.navigate;
-        const onConfirm = this.options.onConfirm;
-        const onRenderError = this.options.onRenderError;
-        // ── The lifecycle of a watch ─────────────────────────────────────────────
-        // A watch subscription follows the MOUNT of an element, and the registry of each
-        // instance in the incremental renderer manages it: an element of the first render
-        // registers then, and an element that appears later, from a visibility that becomes
-        // true or from a repeat item that the code appends, registers at that moment, with
-        // the same skip-on-mount baseline. The renderer releases a subscription when its
-        // element unmounts, from a visibility that becomes false or from a repeat item that
-        // the code removes. It also releases each subscription on a view change, at the top of
-        // this method, and on a disconnect().
-        //
-        // A stable element does NOT receive a new watch on each rerender. The code registers
-        // the update subscription below with the store before the watch subscriptions of
-        // renderSpec, and @xstate/store notifies in the order of the insertion. If a render
-        // in place removed the watchers and made them again, each old watcher would die in
-        // the queue, before it fires, and each new watcher would take the snapshot after the
-        // update as its baseline. A watch action would then fire never. Therefore the registry
-        // keeps the ORIGINAL subscription, with its baseline and its position in the
-        // notification, whenever the code only renders an instance again. It registers a
-        // real new mount only.
-        //
-        // Each registered cleanup is idempotent, and the Set watchCleanups also holds it.
-        // Therefore a second call here, after the incremental renderer released it already, is
-        // safe.
-        const renderOptions = {
-            send,
-            handlers,
-            ...(onRenderError !== undefined ? { onRenderError } : {}),
-            ...(functions !== undefined ? { functions } : {}),
-            ...(directives !== undefined ? { directives } : {}),
-            ...(loading !== undefined ? { loading } : {}),
-            onWatchSetup: (cleanup) => {
-                // Wrap each cleanup. A call of the wrapper, from the disconnect() here or from the
-                // view change here, OR from the incremental renderer when the element of the cleanup
-                // unmounts, also removes the cleanup from the Set. The code returns the wrapper.
-                // Therefore the incremental renderer registers THIS wrapper and calls it on a
-                // release, and the Set stays in step with the live subscriptions.
-                const entry = () => {
-                    this.watchCleanups.delete(entry);
-                    cleanup();
-                };
-                this.watchCleanups.add(entry);
-                return entry;
-            },
-            ...(validationFunctions !== undefined ? { validationFunctions } : {}),
-            ...(navigate !== undefined ? { navigate } : {}),
-            ...(onConfirm !== undefined ? { onConfirm } : {}),
-        };
-        // ── The incremental updates ─────────────────────────────────────────────
-        // A store update rebuilds the complete tree no longer: the incremental renderer
-        // compares the previous snapshot and the next snapshot on the tracked $state paths of
-        // each element, and it renders the elements of the change again, in place. An element
-        // without a state binding keeps the identity of its DOM node. Therefore the focus, the
-        // selection, and the scroll position survive an update of another element. A view
-        // transition still rebuilds everything, because this method runs again.
-        const incremental = createIncrementalRenderer(view, guardedStore, this.registry, this.container, renderOptions);
-        this.incremental = incremental;
-        this.lastRoot = view.root;
-        this.lastElements = view.elements;
-        // subscribe passes through the guard without a change, and it keeps the same function
-        // reference. The guard wraps set and update only.
-        this.storeUnsubscribe = guardedStore.subscribe(() => {
-            // The guard: stop when a caller disconnected the PlayRenderer.
-            // This handles the case of a StateStore implementation that fires its subscribed
-            // callbacks synchronously inside its own unsubscribe() call.
-            if (!this.alive)
-                return;
-            // The try CONTAINS a failed update, exactly as the try of render() contains a
-            // failed rebuild. `incremental.update()` resolves the props of every element that
-            // the write touched, and it rebuilds the COMPLETE tree when the store hands back
-            // the snapshot that it held — so a `$computed` function that throws on the new
-            // state aborts the render here. This callback runs from inside `store.update()`,
-            // which an ACTION HANDLER of the host calls, so such a throw left the renderer
-            // through a path that no option of this class covers: `onError` heard nothing,
-            // the dead tree stayed on the screen, and the failure reached the caller of the
-            // action instead. The containment of a failure of the view is one rule, and it
-            // holds on every path that renders.
-            try {
-                incremental.update();
-            }
-            catch (error) {
-                this.failView(error);
-            }
-        });
-        incremental.render();
-    }
-}
+* PlayRenderer connects the `currentView` atom of an actor to the DOM renderer.
+*
+* It watches `actor.currentView` through the atoms. It renders each
+* `DomComponentRenderer` function into `container` on every view transition.
+* `disconnect()` clears the container.
+*
+* Every option of `PlayDomOptions`, which extends `UIProviderOptions`, goes into
+* `DomRenderContext` on each render pass:
+* - `functions` — the named compute functions of a `{ $computed: "name" }` prop expression
+* - `directives` — your own dynamic values with a `$` prefix, from `defineDirective`. The renderer resolves them with the props
+* - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`
+* - `navigate` — the navigation callback. The renderer calls it for an `onSuccess: { navigate: "..." }` action binding
+* - `onRenderError` — the renderer calls it with `(error, name, info)` for each failure that the inner renderer reports
+*
+* **The preferred use, with `registryResult`:**
+* ```typescript
+* import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+*
+* const registryResult = defineRegistry(catalog, { components, actions });
+* const renderer = new PlayRenderer(container, actor, registryResult.registry, {
+*   registryResult, // it connects setState and getState of the xstate store for you
+*   navigate: (path) => myRouter.push(path),
+*   functions: { fullName: (args) => `${args.first} ${args.last}` },
+* });
+* renderer.connect();
+* // Later:
+* renderer.disconnect();
+* ```
+*
+* **The controlled store mode** — you give your own `StateStore`:
+* ```typescript
+* import { createAtom } from "@xmachines/play-atom";
+* import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
+*
+* const atom  = createAtom({ username: "" });
+* const store = xstateStoreStateStore({ atom });
+* const renderer = new PlayRenderer(container, actor, registry, { registryResult, store });
+* renderer.connect();
+* ```
+*
+* A second `connect()` is safe. A `connect()` call on a connected renderer
+* disconnects it first. Therefore the renderer holds no second render
+* subscription.
+*/
+var PlayRenderer = class {
+	container;
+	actor;
+	registry;
+	options;
+	/**
+	* True from the start of `connect()` to the end of `disconnect()`.
+	*
+	* The watcher cannot answer this question. `connect()` installs it AFTER the
+	* synchronous first render, so a host that calls `connect()` again from the `onError`
+	* of that render finds no watcher, and a test of the watcher alone would skip the
+	* `disconnect()` and leave the guard of the abandoned connection alive for ever.
+	*/
+	connected = false;
+	unwatch = null;
+	storeUnsubscribe = null;
+	/**
+	* The cleanup functions of the live watch subscriptions. This field is a `Set`,
+	* and not an array, so that each registered cleanup function can delete ITSELF on
+	* its call: the incremental renderer releases a watcher when its element unmounts,
+	* and it calls the registered wrapper. The Set therefore shrinks with the live
+	* subscriptions. It does not collect one spent closure for each historical mount of
+	* a view with a long life.
+	*/
+	watchCleanups = /* @__PURE__ */ new Set();
+	/**
+	* The generation of the store behind the tree on the screen, from the lifecycle. A
+	* resolution with the same generation keeps the store: only the /context projection
+	* moved, or a composed view changed its page, so the renderer keeps the tree and the
+	* ephemeral view state, such as a draft or a toggle. A new generation is a new store,
+	* and the renderer builds the tree again. A null emission, from a state with no
+	* meta.view, is a GAP, and not a new view: the DOM goes away, but the lifecycle keeps
+	* the store. A return to the same view therefore builds again around the ephemeral
+	* state that survived, in the same way as the framework providers.
+	*/
+	treeGeneration = void 0;
+	/**
+	* The incremental renderer of the live tree, and the `root` and `elements` of the
+	* spec that it renders. An emission with the same viewKey and the same two
+	* references moved the /context projection alone. An emission with the same
+	* viewKey and a new `elements` object is a new spec of the same view — a composed
+	* view whose page changed, or a streamed chunk — and the renderer takes it in place
+	* through `setSpec`.
+	*/
+	incremental = null;
+	lastRoot = void 0;
+	lastElements = void 0;
+	/** The fallback element, built at the first moment that the renderer shows it. */
+	fallbackElement = null;
+	/**
+	* The view session of the connection, from @xmachines/play-view. It resolves the store
+	* of each view by the rules of the lifecycle — it seeds the store again on a change of
+	* the viewKey, and it refreshes /context in place in every other case — and it hands
+	* this renderer one snapshot for each attempt. Its generation decides whether the live
+	* tree stays. `connect()` makes one, and `disconnect()` drops it with its store.
+	*/
+	session = null;
+	/**
+	* `disconnect()` sets this field to `false` before it calls `storeUnsub()`.
+	* The `rerender` closure reads the flag at its start. Therefore a synchronous
+	* callback from the `StateStore` implementation inside its own `unsubscribe()`
+	* call, which is rare but correct, changes no detached DOM tree.
+	*/
+	alive = true;
+	/**
+	* The depth of the synchronous calls into the inner renderer: `render()`, `setSpec()`
+	* and `update()`. A failure of the root that the inner renderer reports inside such a
+	* call waits for the end of the call. See {@link PlayRenderer.failRoot}.
+	*/
+	innerDepth = 0;
+	/**
+	* The failure of the root that the inner renderer reported, until the renderer
+	* contains it, and the inner renderer that reported it.
+	*/
+	rootFailure = null;
+	/**
+	* The report guard, from @xmachines/play-view.
+	*
+	* It blocks a reset that the host calls from INSIDE the report, and every reset once
+	* the renderer is disconnected. The five renderers share the one implementation.
+	*
+	* `alive` cannot answer the second half. A contained failure sets that flag to `false`
+	* and the next emission sets it back, because it guards the callback of the store
+	* subscription — a reset that a host keeps outlives both.
+	*/
+	guard = createReportGuard(GUARD_MESSAGES);
+	/**
+	* The retry that every report of THIS connection hands the host.
+	*
+	* `connect()` builds one, beside the guard that it belongs to. The four framework
+	* renderers hand the host one reset for the life of the provider, and this field holds
+	* the same rule for the life of the connection.
+	*/
+	retry = this.retryOf(this.guard);
+	/**
+	* @param container - The `HTMLElement` to render into. Each view transition clears it and fills it again.
+	* @param actor     - The actor with the `currentView` atom. It must implement `Viewable`.
+	* @param registry  - The map of the component renderers, usually `registryResult.registry` from `defineRegistry`.
+	* @param options   - The configuration. See {@link PlayDomOptions}:
+	*   - `registryResult`      — it connects `setState` and `state` of the xstate store for you.
+	*   - `store`               — an external `StateStore`, which is the controlled mode. It replaces the values of `spec.state`.
+	*   - `loading`             — the flag of the streaming mode. It stops each warning about an absent child.
+	*   - `functions`           — the named compute functions of a `$computed` prop expression.
+	*   - `directives`          — your own dynamic values with a `$` prefix. The renderer resolves them with the props.
+	*   - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`.
+	*   - `navigate`            — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`.
+	*   - `onRenderError`       — the `(error, name, info)` handler of each failure that the inner renderer reports. It stops the `[json-render]` console line.
+	*   - `onError`             — the `(error, reset)` handler of a failure of the view: a failure of the root, or of a complete rebuild. The renderer contains such a failure always, and this option says where the report goes.
+	*   - `fallback`            — the element to show for every null view, and after a contained failure.
+	*/
+	constructor(container, actor, registry, options = {}) {
+		this.container = container;
+		this.actor = actor;
+		this.registry = registry;
+		this.options = options;
+	}
+	/**
+	* Starts the watch of actor.currentView, and renders into the container.
+	* It renders the first view synchronously, then it subscribes to the atom changes.
+	*
+	* A `connect()` call on a connected renderer, where a `disconnect()` call did not
+	* follow the previous `connect()`, installs a second subscription of the view.
+	* Each view change then renders two times. Therefore this method disconnects the
+	* renderer first.
+	*/
+	connect() {
+		if (this.connected) this.disconnect();
+		this.connected = true;
+		const guard = createReportGuard(GUARD_MESSAGES);
+		this.guard = guard;
+		this.retry = this.retryOf(guard);
+		const session = createViewSession(this.actor, this.options.store, { createStore: (seed) => xstateStoreStateStore({ atom: createAtom(seed) }) });
+		this.session = session;
+		const release = session.subscribe(() => {
+			this.render(session.getSnapshot());
+		});
+		this.unwatch = release;
+	}
+	/**
+	* Stops the watch and clears the container.
+	*/
+	disconnect() {
+		this.connected = false;
+		this.guard.dispose();
+		releaseQuietly(this.unwatch, reportReleaseFailure);
+		this.unwatch = null;
+		this.alive = false;
+		this.releaseTree();
+		this.container.replaceChildren();
+		this.forgetTree();
+		this.session?.dispose();
+		this.session = null;
+	}
+	/**
+	* Releases the store subscription and the watch subscriptions of the tree.
+	*
+	* It captures both and clears both BEFORE a release. Some store implementations fire a
+	* synchronous callback during their unsubscribe(). Without this order, that callback
+	* sees a live storeUnsubscribe, and it enters the rerender path again with an old view
+	* and an old store, or it overwrites watchCleanups before the loop below reaches it.
+	*
+	* See reportReleaseFailure: a throw of one release must skip none of the work below it.
+	* This is code of a caller, and it also runs on the path of a view that WORKS.
+	*/
+	releaseTree() {
+		const storeUnsub = this.storeUnsubscribe;
+		const watchCleanups = [...this.watchCleanups];
+		const incremental = this.incremental;
+		this.storeUnsubscribe = null;
+		this.watchCleanups = /* @__PURE__ */ new Set();
+		this.rootFailure = null;
+		releaseQuietly(storeUnsub, reportReleaseFailure);
+		if (incremental !== null) releaseQuietly(() => incremental.dispose(), reportReleaseFailure);
+		for (const cleanup of watchCleanups) releaseQuietly(cleanup, reportReleaseFailure);
+	}
+	/** Forgets the tree on the screen, so that the next emission builds it again. */
+	forgetTree() {
+		this.treeGeneration = void 0;
+		this.incremental = null;
+		this.lastRoot = void 0;
+		this.lastElements = void 0;
+	}
+	/**
+	* The number of live watch-subscription cleanup functions now.
+	*
+	* @internal This accessor is for a test only. A test asserts with it that the
+	* collection of the watch cleanups holds the live registrations, and that no mount
+	* leaks. It is not part of the public API, and it can change without a notice.
+	*/
+	get watchCleanupCount() {
+		return this.watchCleanups.size;
+	}
+	/**
+	* Brings the screen in line with one snapshot of the view session.
+	*
+	* The session resolved the store already: it refreshed /context in place, or it seeded
+	* a new store, or it recorded the failure of `spec.state`. This method decides the
+	* tree alone.
+	*/
+	render(snapshot) {
+		const { view } = snapshot;
+		if (snapshot.failure) {
+			this.failView(snapshot.failure.error);
+			return;
+		}
+		if (view !== null && this.incremental !== null && this.storeUnsubscribe !== null) {
+			if (snapshot.generation === this.treeGeneration) {
+				const incremental = this.incremental;
+				try {
+					if (view.root !== this.lastRoot || view.elements !== this.lastElements) {
+						this.lastRoot = view.root;
+						this.lastElements = view.elements;
+						this.callInner(incremental, () => incremental.setSpec(view));
+					}
+				} catch (error) {
+					this.failView(error);
+				}
+				return;
+			}
+		}
+		this.clearTree();
+		if (view === null || snapshot.store === null) {
+			this.showFallback();
+			return;
+		}
+		try {
+			this.renderView(view, snapshot.store, snapshot.generation);
+		} catch (error) {
+			this.failView(error);
+		}
+	}
+	/**
+	* Takes the tree of the previous view off the screen, before a rebuild.
+	*
+	* The watch subscriptions of the previous view must go too. Without this step, they
+	* stay active between a view transition and the first store update of the new view.
+	* They then hold a reference to a DOM element that is gone, and the garbage collector
+	* cannot take it.
+	*/
+	clearTree() {
+		this.alive = true;
+		this.releaseTree();
+		this.forgetTree();
+		this.container.replaceChildren();
+	}
+	/**
+	* The end of a render that failed, in ONE place.
+	*
+	* Three paths render — the fast path of a slice, the complete rebuild, and the write
+	* of the store — and each one ends here: through a throw, or through a failure of the
+	* root that the inner renderer reports (see {@link PlayRenderer.failRoot}). The ORDER
+	* is load-bearing: the reset takes the registrations of the dead tree down BEFORE the
+	* report, so a handler of the host that renders again meets a renderer that holds
+	* nothing of the failed attempt. A second copy of the pair is a second chance to put
+	* the two in the other order.
+	*
+	* @param error - The failure that the renderer contains.
+	*/
+	failView(error) {
+		this.resetFailedRebuild();
+		this.contain(error);
+	}
+	/**
+	* Gives a failure that the inner renderer reports to the handler of the host, and
+	* contains a failure of the ROOT as a failure of the view.
+	*
+	* The inner renderer reports each failure one time, with `(error, name, info)`. This
+	* method gives each one to `forwardRenderError` of @xmachines/play-view, which holds
+	* the rule of the five renderers: the `onRenderError` of the host, or the handler of the
+	* registry, or the one `[json-render]` console line.
+	*
+	* A failure of the root — its component, a prop, or its `visible` condition — leaves
+	* no view on the screen. The inner renderer throws it to no caller, so the renderer
+	* contains it here, as it contains a complete rebuild that throws: it shows the
+	* fallback, and it reports the failure to `onError` one time. A handler of the host
+	* also gets it, with `info.kind` `"root"`. Without such a handler, the method writes
+	* no `[json-render]` line for it: the containment reports it to `onError`, or to its
+	* own console line, and a second line would report one failure two times.
+	*
+	* @param owner - The inner renderer that this handler belongs to, or `null` before it exists.
+	*/
+	reportInner(owner, error, name, info) {
+		if (forwardRenderError(this.options.onRenderError, this.registry, error, name, info) && owner !== null) this.failRoot(owner, error);
+	}
+	/**
+	* Contains a failure of the root that the inner renderer reported.
+	*
+	* The report comes in the middle of the work of the inner renderer, which writes the
+	* container after it. The containment therefore waits for the end of that work. Inside
+	* a synchronous call, {@link PlayRenderer.callInner} contains the failure when the call
+	* returns. At the commit point of a store write, which no call of this class holds, a
+	* microtask contains it.
+	*
+	* @param owner - The inner renderer that reported the failure.
+	* @param error - The failure of the root.
+	*/
+	failRoot(owner, error) {
+		if (this.incremental !== owner || this.rootFailure !== null) return;
+		this.rootFailure = {
+			error,
+			owner
+		};
+		if (this.innerDepth > 0) return;
+		queueMicrotask(() => this.settleRoot());
+	}
+	/**
+	* Hands the failure of the root that waits to the session, when it belongs to the
+	* live tree.
+	*
+	* The four framework providers take the same path: `failView` of the session records
+	* the failure in a new snapshot, and it gives the next attempt a new generation. The
+	* session then notifies this renderer, and `render()` contains the failed snapshot
+	* with {@link PlayRenderer.failView}: it clears the tree, shows the fallback, and
+	* reports to `onError` one time. The session has no `onFailure` here, so it reports
+	* nothing of its own.
+	*/
+	settleRoot() {
+		const failure = this.rootFailure;
+		this.rootFailure = null;
+		if (failure === null || this.incremental !== failure.owner) return;
+		this.session?.failView(failure.error);
+	}
+	/**
+	* Runs one synchronous call into the inner renderer, and then contains a failure of the
+	* root that the call reported.
+	*
+	* @param owner - The inner renderer of the call.
+	* @param call - The call: `render()`, `setSpec()` or `update()`.
+	*/
+	callInner(owner, call) {
+		this.innerDepth += 1;
+		try {
+			call();
+		} finally {
+			this.innerDepth -= 1;
+		}
+		if (this.innerDepth === 0 && this.rootFailure?.owner === owner) this.settleRoot();
+	}
+	/**
+	* Clears the screen of the failed view, shows the fallback, and reports the failure.
+	*
+	* The renderer contains such a failure ALWAYS. No option turns the containment on,
+	* and none turns it off: `onError` says where the report goes, and `fallback` says
+	* what the empty container shows. The four framework renderers hold the same rule,
+	* because an error boundary of a framework is not an option that a caller turns off.
+	* A host that must escalate a failure raises it from a task of its own —
+	* `rethrowLater(error)` of `@xmachines/core/utils` — because the guard contains a handler
+	* that throws, exactly as the four framework renderers do.
+	*
+	* The container is cleared FIRST. The fast path of a slice holds the live tree of the
+	* previous emission, and that tree is dead as soon as the refresh throws, so the
+	* renderer must not keep it on the screen. A clear container also lets the fallback
+	* stand alone.
+	*
+	* The SCREEN comes first, and the report second: a handler that throws — a reporter
+	* that fails, or one that re-raises to escalate — must not defeat the containment
+	* that it was given to observe. With the order reversed the container stays empty AND
+	* the error escapes, which is both outcomes that the containment exists to prevent.
+	*/
+	contain(error) {
+		this.container.replaceChildren();
+		this.showFallback();
+		const { onError } = this.options;
+		const guard = this.guard;
+		const retry = this.retry;
+		guard.report(error, onError && (() => onError(error, retry)));
+	}
+	/**
+	* Builds the retry that one report hands the host.
+	*
+	* The read of the atom happens at the moment of the CALL: a retry that held the view
+	* that failed would take a host off the healthy screen and back onto the one that
+	* threw.
+	*
+	* The retry belongs to the guard of ITS connection, and it asks that guard alone. A
+	* host may KEEP the callback — a "Retry" button of a toast outlives the route that
+	* opened it — and `disconnect()` disposes the guard that was live then. `connect()`
+	* disconnects a connected renderer first, so every guard that leaves the field is a
+	* disposed guard, and a retry of an older connection stays dead. The rule of the prop
+	* is one rule: a reset after `disconnect()` does nothing.
+	*
+	* @param guard - The guard of the connection that this retry belongs to.
+	*/
+	retryOf(guard) {
+		return () => {
+			if (guard.blocked()) return;
+			this.session?.retry();
+		};
+	}
+	/**
+	* Appends the fallback element to the container, which the caller cleared already.
+	* The renderer calls it for a null view, and after a failure of a rebuild that it
+	* contains. Both callers clear the container first. `appendChild` moves the node.
+	* Therefore a second call adds no copy.
+	*/
+	showFallback() {
+		const fallback = this.options.fallback;
+		if (fallback == null) return;
+		try {
+			this.fallbackElement ??= typeof fallback === "function" ? fallback() : fallback;
+			this.container.appendChild(this.fallbackElement);
+		} catch (error) {
+			console.error("[@xmachines/play-dom] the fallback of PlayRenderer failed to build. The container stays empty.", error);
+		}
+	}
+	/**
+	* A rebuild that fails must not leave the guard of the fast path armed on a dead
+	* tree, because the container is empty already. Therefore this code resets the view
+	* identity. The next emission, also one with the same viewKey, then makes a
+	* complete render again. It does not patch a store that nothing shows.
+	*
+	* It releases the watch subscriptions of the dead tree too. A complete rebuild
+	* releases them before it builds again, and disconnect() releases them at the end of
+	* the life of the renderer — but a failure takes the DOM down HERE, between those two
+	* moments. Without this step one update of the store of the host runs every watch
+	* action of a tree that nothing shows, against detached elements, with `send` still
+	* bound to the actor. The fast path of a slice leaves a live tree of its own, and it
+	* reaches this code only when it fails.
+	*/
+	resetFailedRebuild() {
+		this.alive = false;
+		this.releaseTree();
+		this.forgetTree();
+	}
+	/**
+	* The tail of a complete rebuild, which can throw. See the catch block of render().
+	*
+	* @param view - The view to render.
+	* @param guardedStore - The store of the view, from the session. Everything that the
+	*   spec can write through, which includes $bindState, setState, and a chained set,
+	*   receives the GUARDED store: /context is read-only to the spec, because the machine
+	*   context changes through an event only.
+	* @param generation - The generation of that store, which the tree records.
+	*/
+	renderView(view, guardedStore, generation) {
+		const send = this.actor.send.bind(this.actor);
+		const handlers = this.options.registryResult ? bindStoreHandlers(this.options.registryResult, () => guardedStore) : {};
+		const loading = this.options.loading;
+		const functions = this.options.functions;
+		const directives = this.options.directives;
+		const validationFunctions = this.options.validationFunctions;
+		const navigate = this.options.navigate;
+		const onConfirm = this.options.onConfirm;
+		const confirmDialog = this.options.confirmDialog;
+		let owner = null;
+		const onRenderError = (error, name, info) => {
+			this.reportInner(owner, error, name, info);
+		};
+		const renderOptions = {
+			send,
+			handlers,
+			onRenderError,
+			...functions !== void 0 ? { functions } : {},
+			...directives !== void 0 ? { directives } : {},
+			...loading !== void 0 ? { loading } : {},
+			onWatchSetup: (cleanup) => {
+				const entry = () => {
+					this.watchCleanups.delete(entry);
+					cleanup();
+				};
+				this.watchCleanups.add(entry);
+				return entry;
+			},
+			...validationFunctions !== void 0 ? { validationFunctions } : {},
+			...navigate !== void 0 ? { navigate } : {},
+			...onConfirm !== void 0 ? { onConfirm } : {},
+			...confirmDialog !== void 0 ? { confirmDialog } : {}
+		};
+		const incremental = createIncrementalRenderer(view, guardedStore, this.registry, this.container, renderOptions);
+		owner = incremental;
+		this.incremental = incremental;
+		this.treeGeneration = generation;
+		this.lastRoot = view.root;
+		this.lastElements = view.elements;
+		this.storeUnsubscribe = guardedStore.subscribe(() => {
+			if (!this.alive) return;
+			try {
+				this.callInner(incremental, () => incremental.update());
+			} catch (error) {
+				this.failView(error);
+			}
+		});
+		this.callInner(incremental, () => incremental.render());
+	}
+};
+//#endregion
+export { PlayRenderer };
+
 //# sourceMappingURL=PlayRenderer.js.map