@xmachines/play-dom 2.1.1 → 3.0.0

package/dist/create-play-ui.js

@@ -6,9 +6,9 @@
  * it returns a `disconnect` cleanup function.
  *
  * The factory holds the factory options (`functions`, `validationFunctions`,
- * `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and
- * it applies them on every `mount()` call. Give the mount options (`store` and
- * `loading`) to the `mount()` call itself, through `MountOptions`.
+ * `navigate`, `onRenderError`, `onError`, and `fallback`) from the moment of its
+ * creation, and it applies them on every `mount()` call. Give the mount options
+ * (`store` and `loading`) to the `mount()` call itself, through `MountOptions`.
  *
  * This factory is parallel to `<PlayUIProvider registryResult={...}>` in the
  * framework renderers.
@@ -31,6 +31,7 @@
  *
  * @packageDocumentation
  */
+import { asCleanup } from "@xmachines/play";
 import { PlayRenderer } from "./PlayRenderer.js";
 /**
  * Creates the mount function of the complete DOM renderer.
@@ -47,11 +48,15 @@ import { PlayRenderer } from "./PlayRenderer.js";
  *   - `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.
- *   - `fallback`            — the element to show when the first view of the actor is `null`.
- * @returns The `MountFn`: `(actor, container, mountOptions?) → disconnect`
+ *   - `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 content to show when the view of the actor is `null`, and after a contained
+ *                             failure of a rebuild. Give a FUNCTION when the factory mounts more than one
+ *                             time, so that each renderer owns its own element.
+ * @returns The {@link DisposablePlayUI}: `(actor, container, mountOptions?) → disconnect`
  */
 export function createPlayUI(registryResult, options = {}) {
-    const { onRenderError, fallback, functions, directives, validationFunctions, navigate, onConfirm, } = options;
+    const { onRenderError, onError, fallback, functions, directives, validationFunctions, navigate, onConfirm, } = options;
     return function mount(actor, container, mountOptions) {
         // Each option of UIProviderOptions (onRenderError, functions, validationFunctions,
         // and navigate) goes directly through PlayDomOptions, then PlayRenderer, then
@@ -66,18 +71,29 @@ export function createPlayUI(registryResult, options = {}) {
             ...(navigate !== undefined && { navigate }),
             ...(onConfirm !== undefined && { onConfirm }),
             ...(onRenderError !== undefined && { onRenderError }),
+            // PlayRenderer owns both of them now. It contains a rebuild that throws always,
+            // and it shows the fallback for every null view and after each contained
+            // failure. The factory therefore forwards the two options, and it appends
+            // nothing itself.
+            ...(onError !== undefined && { onError }),
+            // The producer travels UNCHANGED. PlayRenderer calls it at the first moment it
+            // needs the element, and it holds the memo — one mount builds one renderer, so
+            // a second memo here would hold the same element for the same lifetime. A
+            // producer gives every renderer its own element; a single element that every
+            // mount shares would pass from one container to the next on each null view,
+            // because appendChild moves a node.
+            ...(fallback != null && { fallback }),
         };
         const renderer = new PlayRenderer(container, actor, registryResult.registry, rendererOptions);
+        // connect() renders the first view synchronously, and PlayRenderer appends the
+        // fallback itself when that view is null.
+        // It needs no `try`: PlayRenderer contains a failed rebuild AND a handler of the
+        // host that throws, so `connect()` returns for every view. `mount()` therefore
+        // always reaches the `return` below, and the caller always receives the release.
         renderer.connect();
-        // Handle the fallback of a null view on the first mount.
-        // connect() calls _render() synchronously. Therefore the container holds the view
-        // already at this point, when actor.currentView is not null.
-        if (fallback != null && container.childNodes.length === 0) {
-            container.appendChild(fallback);
-        }
-        return function disconnect() {
+        return asCleanup(function disconnect() {
             renderer.disconnect();
-        };
+        });
     };
 }
 //# sourceMappingURL=create-play-ui.js.map

package/dist/create-play-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-play-ui.js","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAuCjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAC3B,cAAoC,EACpC,UAA+B,EAAE;IAEjC,MAAM,EACL,aAAa,EACb,QAAQ,EACR,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,QAAQ,EACR,SAAS,GACT,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY;QACnD,mFAAmF;QACnF,8EAA8E;QAC9E,qCAAqC;QACrC,MAAM,eAAe,GAAG;YACvB,cAAc;YACd,GAAG,CAAC,YAAY,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;YACvE,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;YAC7E,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;YAC/C,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,EAAE,mBAAmB,EAAE,CAAC;YACjE,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC;SACrD,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAChC,SAAS,EACT,KAAK,EACL,cAAc,CAAC,QAAQ,EACvB,eAAe,CACf,CAAC;QACF,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEnB,yDAAyD;QACzD,kFAAkF;QAClF,6DAA6D;QAC7D,IAAI,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAED,OAAO,SAAS,UAAU;YACzB,QAAQ,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-play-ui.js","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAI1D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAiEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAC3B,cAAoC,EACpC,UAA+B,EAAE;IAEjC,MAAM,EACL,aAAa,EACb,OAAO,EACP,QAAQ,EACR,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,QAAQ,EACR,SAAS,GACT,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY;QACnD,mFAAmF;QACnF,8EAA8E;QAC9E,qCAAqC;QACrC,MAAM,eAAe,GAAG;YACvB,cAAc;YACd,GAAG,CAAC,YAAY,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;YACvE,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;YAC7E,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;YAC/C,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,EAAE,mBAAmB,EAAE,CAAC;YACjE,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC;YACrD,gFAAgF;YAChF,yEAAyE;YACzE,0EAA0E;YAC1E,kBAAkB;YAClB,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;YACzC,+EAA+E;YAC/E,+EAA+E;YAC/E,0EAA0E;YAC1E,6EAA6E;YAC7E,4EAA4E;YAC5E,oCAAoC;YACpC,GAAG,CAAC,QAAQ,IAAI,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC;SACrC,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAChC,SAAS,EACT,KAAK,EACL,cAAc,CAAC,QAAQ,EACvB,eAAe,CACf,CAAC;QACF,+EAA+E;QAC/E,0CAA0C;QAC1C,iFAAiF;QACjF,+EAA+E;QAC/E,iFAAiF;QACjF,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEnB,OAAO,SAAS,CAAC,SAAS,UAAU;YACnC,QAAQ,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;AACH,CAAC"}

package/dist/create-renderer.d.ts

@@ -52,6 +52,7 @@
  *
  * @packageDocumentation
  */
+import { type Cleanup } from "@xmachines/play";
 import type { AbstractActor, Viewable } from "@xmachines/play-actor";
 import type { AnyActorLogic } from "xstate";
 import type { Catalog } from "@xmachines/json-render-core";
@@ -81,5 +82,5 @@ import type { PlayDomOptions } from "./types.js";
  * `CreatePlayUIOptions`. You can also use `defineRegistry` with `PlayRenderer`
  * directly.
  */
-export declare function createRenderer<C extends Catalog>(catalog: C, componentMap: ComponentRegistry<C>): (actor: AbstractActor<AnyActorLogic> & Viewable, container: HTMLElement, options?: Omit<PlayDomOptions, "registryResult">) => () => void;
+export declare function createRenderer<C extends Catalog>(catalog: C, componentMap: ComponentRegistry<C>): (actor: AbstractActor<AnyActorLogic> & Viewable, container: HTMLElement, options?: Omit<PlayDomOptions, "registryResult">) => Cleanup;
 //# sourceMappingURL=create-renderer.d.ts.map

package/dist/create-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-renderer.d.ts","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,CACF,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,KAC5C,MAAM,IAAI,CAWd"}
+{"version":3,"file":"create-renderer.d.ts","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,CACF,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,KAC5C,OAAO,CAWX"}

package/dist/create-renderer.js

@@ -52,6 +52,7 @@
  *
  * @packageDocumentation
  */
+import { asCleanup } from "@xmachines/play";
 import { PlayRenderer } from "./PlayRenderer.js";
 import { defineRegistry } from "@xmachines/json-render-dom";
 /**
@@ -86,7 +87,7 @@ export function createRenderer(catalog, componentMap) {
             registryResult,
         });
         renderer.connect();
-        return () => renderer.disconnect();
+        return asCleanup(() => renderer.disconnect());
     };
 }
 //# sourceMappingURL=create-renderer.js.map

package/dist/create-renderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-renderer.js","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAU,EACV,YAAkC;IAMlC,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAE7E,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAG,EAAE;QACnD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;YAC5E,GAAG,OAAO;YACV,cAAc;SACd,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;IACpC,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-renderer.js","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAM1D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAU,EACV,YAAkC;IAMlC,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAE7E,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAG,EAAE;QACnD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;YAC5E,GAAG,OAAO;YACV,cAAc;SACd,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -5,9 +5,9 @@
  *
  * **The XMachines layer**, in this package:
  * - `createRenderer()`  — the one-call factory. It returns `mount(actor, container, options?) → disconnect`
- * - `createPlayUI()`    — the complete factory, with every option. It returns a `MountFn`
+ * - `createPlayUI()`    — the complete factory, with every option. It returns a `DisposablePlayUI`
  * - `PlayRenderer`      — the renderer class, with a `connect()` and `disconnect()` lifecycle
- * - `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `MountOptions`
+ * - `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `DisposablePlayUI`, `MountOptions`
  *
  * **The json-render layer**, re-exported from @xmachines/json-render-dom:
  * - `defineRegistry`    — it builds a catalog-typed DomRegistry
@@ -28,10 +28,11 @@
 export { PlayRenderer } from "./PlayRenderer.js";
 export { createRenderer } from "./create-renderer.js";
 export { createPlayUI } from "./create-play-ui.js";
-export type { MountFn, MountOptions } from "./create-play-ui.js";
+export type { MountFn, DisposablePlayUI, MountOptions } from "./create-play-ui.js";
 export type { PlayDomOptions, CreatePlayUIOptions } from "./types.js";
 export { defineRegistry, renderSpec, schema, createValidationRegistry, } from "@xmachines/json-render-dom";
 export type { ValidationRegistry, FieldValidationState } from "@xmachines/json-render-dom";
 export type { RenderSpecOptions } from "@xmachines/json-render-dom";
 export type { ConfirmHandler, EventHandle, SetState, RenderErrorHandler, UIProviderOptions, CatalogHasActions, BaseComponentProps, DomRenderContext, DomComponentRenderer, ComponentContext, ComponentFn, ComponentRegistry, Actions, ActionFn, DefineRegistryOptions, DefineRegistryResult, DomRegistry, DomSchema, } from "@xmachines/json-render-dom";
+export { type Cleanup } from "@xmachines/play";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGjE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EACN,cAAc,EACd,UAAU,EACV,MAAM,EACN,wBAAwB,GACxB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EACX,cAAc,EACd,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,OAAO,EACP,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACT,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnF,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EACN,cAAc,EACd,UAAU,EACV,MAAM,EACN,wBAAwB,GACxB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EACX,cAAc,EACd,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,OAAO,EACP,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,SAAS,GACT,MAAM,4BAA4B,CAAC;AAKpC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -5,9 +5,9 @@
  *
  * **The XMachines layer**, in this package:
  * - `createRenderer()`  — the one-call factory. It returns `mount(actor, container, options?) → disconnect`
- * - `createPlayUI()`    — the complete factory, with every option. It returns a `MountFn`
+ * - `createPlayUI()`    — the complete factory, with every option. It returns a `DisposablePlayUI`
  * - `PlayRenderer`      — the renderer class, with a `connect()` and `disconnect()` lifecycle
- * - `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `MountOptions`
+ * - `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `DisposablePlayUI`, `MountOptions`
  *
  * **The json-render layer**, re-exported from @xmachines/json-render-dom:
  * - `defineRegistry`    — it builds a catalog-typed DomRegistry
@@ -31,4 +31,9 @@ export { createRenderer } from "./create-renderer.js";
 export { createPlayUI } from "./create-play-ui.js";
 // @xmachines/json-render-dom. This package re-exports it, for the convenience of a consumer
 export { defineRegistry, renderSpec, schema, createValidationRegistry, } from "@xmachines/json-render-dom";
+// The release protocol of @xmachines/play. This package's own published `.d.ts` names
+// exactly these, so a consumer reads them from here and needs no second manifest
+// entry. It names `asCleanup` nowhere: a consumer of this package RECEIVES a
+// release, and builds one only with @xmachines/play itself.
+export {} from "@xmachines/play";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,4FAA4F;AAC5F,OAAO,EACN,cAAc,EACd,UAAU,EACV,MAAM,EACN,wBAAwB,GACxB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,4FAA4F;AAC5F,OAAO,EACN,cAAc,EACd,UAAU,EACV,MAAM,EACN,wBAAwB,GACxB,MAAM,4BAA4B,CAAC;AAuBpC,sFAAsF;AACtF,iFAAiF;AACjF,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAgB,MAAM,iBAAiB,CAAC"}

package/dist/types.d.ts

@@ -47,6 +47,82 @@ export interface PlayDomOptions extends UIProviderOptions {
      * This option matches the `loading` prop of the framework renderer providers.
      */
     loading?: boolean;
+    /**
+     * The optional handler of a failure of a complete rebuild of the view.
+     *
+     * This option is NOT the same as `onRenderError`, which {@link UIProviderOptions}
+     * gives: the inner renderer routes a render error of one component, and a rejection
+     * of one action handler, to `onRenderError`. It contains each of them per element,
+     * and the rebuild continues. `onError` receives the failure of the complete rebuild
+     * that no per-element boundary caught.
+     *
+     * The renderer CONTAINS a rebuild that throws, with this option and without it: it
+     * resets the state of the failed rebuild, so that the next emission makes a complete
+     * render again, and it clears the container. `connect()` renders the first view
+     * synchronously, so a bad initial view makes `connect()` throw no more.
+     *
+     * A WRITE of the store takes the same path. The renderer resolves the props of every
+     * element that the write touched, so a `$computed` function that throws on the new
+     * state aborts that render too. The renderer contains such a failure as well, and the
+     * action handler that wrote the state receives no exception.
+     *
+     * This option says WHERE the report goes. Without it, the renderer writes the
+     * contained failure to `console.error`.
+     *
+     * A handler that THROWS reaches no caller: the renderer contains that throw too, and
+     * it writes the throw to `console.error`. A host that must escalate a failure raises
+     * it from a task of its own — `queueMicrotask(() => { throw error; })` — which
+     * reaches the global handler of the page and leaves the containment whole. The five
+     * renderers hold this one rule.
+     *
+     * The second parameter is the RESET, for a retry that the host starts — a "Retry"
+     * button of its own. It renders the view that the actor holds at the MOMENT OF THE
+     * CALL, so a host that keeps the callback cannot rewind the screen to the view that
+     * failed. A reset that the host calls from inside this handler does nothing, because
+     * no input changed between the two attempts, and a reset after `disconnect()` does
+     * nothing.
+     *
+     * A reset belongs to ONE connection. `connect()` starts a connection, and the reset of
+     * a report of an older connection does nothing. A host that calls `connect()` again
+     * from inside this handler abandons the connection that reported. The "Retry" button
+     * of that report must not render into the connection that took its place. Call the
+     * reset of the newest report.
+     *
+     * This option matches the `onError` prop of the framework renderer providers, and the
+     * five renderers hold the same three rules for the reset.
+     */
+    onError?: (error: unknown, reset: () => void) => void;
+    /**
+     * The optional element that the renderer shows when `currentView` is `null`, and
+     * after a failure of a rebuild that it contains.
+     *
+     * The renderer shows it for EVERY null view, and not for the first mount only: a view
+     * that returns to `null` after a view that was not `null` also shows it. The four
+     * framework providers hold the same rule for their placeholder content.
+     *
+     * The renderer shows it after a failure of a rebuild too. This option turns nothing
+     * on: the renderer contains such a failure always, and this option says only what the
+     * empty container shows. The next view that renders clears the container, which
+     * removes the element.
+     *
+     * **One element belongs to one renderer.** `appendChild` MOVES a node. Two renderers
+     * that hold the same element therefore take it from each other on every null view,
+     * and the container of the first one goes empty without a notice. Build one element
+     * for each `PlayRenderer`.
+     *
+     * A FUNCTION also works here. The renderer calls it at the first moment that it needs
+     * the element, and it keeps the result, so a renderer whose view is never null builds
+     * nothing. {@link CreatePlayUIOptions.fallback} passes such a function for each
+     * mount.
+     *
+     * A producer that THROWS is contained on BOTH paths — a null view, and a rebuild that
+     * failed — and the renderer writes it to `console.error` and NOT to
+     * {@link PlayDomOptions.onError}. On the second path the renderer calls the producer
+     * from inside the containment of the view, and a second trip through `onError` would
+     * report the failure of the fallback as a failure of the view. The container stays
+     * empty.
+     */
+    fallback?: HTMLElement | (() => HTMLElement) | null;
 }
 /**
  * The options of `createPlayUI()`, the complete DOM factory.
@@ -56,23 +132,39 @@ export interface PlayDomOptions extends UIProviderOptions {
  * holds all of them from the moment of its creation, and it gives them to
  * `PlayRenderer` on every `mount()` call.
  *
+ * It also takes {@link PlayDomOptions.onError}, which the factory forwards without a
+ * change: `PlayRenderer` owns it, and it receives every failure of a rebuild that the
+ * renderer contains. Read that entry for the complete rule. `fallback` below says what
+ * the factory adds to {@link PlayDomOptions.fallback}.
+ *
  * This type is parallel to the props of `PlayUIProvider` in the framework renderers.
  *
  * @see createPlayUI
  */
-export interface CreatePlayUIOptions extends UIProviderOptions {
+export interface CreatePlayUIOptions extends UIProviderOptions, Pick<PlayDomOptions, "onError"> {
     /**
-     * The optional fallback element. The factory shows it when `currentView` is `null` on the **first mount** only.
+     * The optional fallback content — see {@link PlayDomOptions.fallback} for what the
+     * renderer does with it. The factory shows it for every null view, and after a
+     * failure of a rebuild that the renderer contains.
+     *
+     * **Give a FUNCTION when the factory mounts more than one time.** ONE factory serves
+     * every `mount()` call, and `appendChild` MOVES a node. A single element therefore
+     * passes from one container to the next on every null view, and the container that
+     * loses it goes empty without a notice. A function runs one time for each mount, so
+     * every renderer owns its own element:
      *
-     * The factory appends the fallback directly after `mount()`, when the container is
-     * empty at that moment, which means that the first view of the actor is `null`.
+     * ```typescript
+     * const mount = createPlayUI(registryResult, {
+     * 	fallback: () => {
+     * 		const element = document.createElement("p");
+     * 		element.textContent = "Loading…";
+     * 		return element;
+     * 	},
+     * });
+     * ```
      *
-     * **Limitation:** when the view of the actor becomes `null` after the mount, the
-     * renderer clears the container, and it does NOT append this fallback again. For a
-     * dynamic fallback, which follows a null view after a view that was not null, use
-     * `PlayRenderer` directly and wrap the `actor.currentView` signal to add the
-     * fallback content.
+     * An element stays correct for a factory that mounts one time.
      */
-    fallback?: HTMLElement | null;
+    fallback?: HTMLElement | (() => HTMLElement) | null;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACxD;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAEtC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC7D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACxD;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAEtC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC;IAC9F;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,GAAG,IAAI,CAAC;CACpD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-dom",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering",
   "keywords": [
     "actor",
@@ -46,17 +46,17 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xmachines/play": "2.1.1",
-    "@xmachines/play-actor": "2.1.1",
-    "@xmachines/play-signals": "2.1.1"
+    "@xmachines/play": "3.0.0",
+    "@xmachines/play-actor": "3.0.0",
+    "@xmachines/play-signals": "3.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^26.2.0",
     "@vitest/browser-playwright": "^4.1.11",
-    "@xmachines/json-render-core": "^0.20.0-xm.2",
-    "@xmachines/json-render-dom": "^0.20.0-xm.2",
-    "@xmachines/json-render-xstate": "^0.20.0-xm.2",
+    "@xmachines/json-render-core": "^0.20.0-xm.4",
+    "@xmachines/json-render-dom": "^0.20.0-xm.4",
+    "@xmachines/json-render-xstate": "^0.20.0-xm.4",
     "@xstate/store": "^3.17.0",
     "oxfmt": "^0.64.0",
     "oxlint": "^1.79.0",
@@ -67,9 +67,9 @@
     "zod": "^4.4.1"
   },
   "peerDependencies": {
-    "@xmachines/json-render-core": "^0.20.0-xm.2",
-    "@xmachines/json-render-dom": "^0.20.0-xm.2",
-    "@xmachines/json-render-xstate": "^0.20.0-xm.2",
+    "@xmachines/json-render-core": "^0.20.0-xm.4",
+    "@xmachines/json-render-dom": "^0.20.0-xm.4",
+    "@xmachines/json-render-xstate": "^0.20.0-xm.4",
     "@xstate/store": "^3.17.0",
     "xstate": "^5.31.0"
   },