@xmachines/docs 4.0.0 → 5.0.1

package/api/@xmachines/play-dom/README.md

@@ -2,9 +2,9 @@
 
 # @xmachines/play-dom
 
-Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
+Vanilla DOM renderer for XMachines Play architecture with atom-driven rendering.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.1-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -15,9 +15,13 @@ pnpm add @xmachines/play-dom
 **Peer dependencies:**
 
 ```bash
-pnpm add @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
+pnpm add @xmachines/play @xmachines/play-atom @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
 ```
 
+`@xstate/store` is the peer of [`@xmachines/play-atom`](../play-atom/README.md), and not of this
+package: this package reads the atom through [`@xmachines/play-atom`](../play-atom/README.md) and
+imports the engine in no source file. Install ONE copy of it.
+
 ## Quick Start
 
 ```typescript
@@ -171,7 +175,7 @@ renderer.disconnect();
 **Controlled store mode.** Give the renderer an external `StateStore`. The renderer then shares the state with the other parts of your application:
 
 ```typescript
-import { createAtom } from "@xstate/store";
+import { createAtom } from "@xmachines/play-atom";
 import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
 
 const atom = createAtom<Record<string, unknown>>({ username: "" });
@@ -286,7 +290,7 @@ Without `onRenderError`, the renderer writes all three types of error to `consol
 **Read this if you catch what `mount()` or `connect()` throws.**
 
 In 2.2.0 the renderer had no containment. A view that failed the rebuild threw out of
-`mount()` and out of the callback of the signal watcher, so a `try` of the host, an error
+`mount()` and out of the callback of the atom watcher, so a `try` of the host, an error
 boundary of the framework around it, or the global handler of the page received it.
 
 In 2.3.0 the renderer contains such a failure ALWAYS. No option turns the containment on,
@@ -363,15 +367,15 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 
 ### XMachines Layer
 
-| Export                                   | Kind     | Description                                                         |
-| ---------------------------------------- | -------- | ------------------------------------------------------------------- |
-| `createRenderer(catalog, components)`    | function | The one-call factory. Its `mount` hands a `Cleanup` back            |
-| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `MountFn`                        |
-| `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle |
-| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers             |
-| `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                              |
-| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()` |
-| `asCleanup`, `Cleanup`                   | —        | The release a mount returns, re-exported from `@xmachines/play`     |
+| Export                                   | Kind     | Description                                                                          |
+| ---------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| `createRenderer(catalog, components)`    | function | The one-call factory. Its `mount` hands a `Cleanup` back                             |
+| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `MountFn`                                         |
+| `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle                  |
+| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                              |
+| `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                                               |
+| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()`                  |
+| `asCleanup`, `Cleanup`                   | —        | The release a mount returns, re-exported from [`@xmachines/play`](../play/README.md) |
 
 ### Key Types
 
@@ -391,15 +395,15 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 | `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                                               |
 | `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                                     |
 | `DomSchema`              | Type of the `schema` export                                                                                   |
-| `Cleanup`                | The release of a mount, re-exported from `@xmachines/play`                                                    |
+| `Cleanup`                | The release of a mount, re-exported from [`@xmachines/play`](../play/README.md)                               |
 
 ## Rendering Behavior
 
 - **The first render is synchronous** — the renderer fills the container before `connect()` returns.
-- **A signal-driven render waits for a microtask** — `watchSignal` puts each update on the next tick of the microtask queue.
+- **An atom-driven render waits for a microtask** — `watchAtom` puts each update on the next tick of the microtask queue.
 - **A null view** clears the container, and the renderer then shows the `fallback` element when you give one. It shows it for every null view, and not for the first mount only — the four framework providers hold the same rule for their placeholder content.
 - **A second `connect()` is safe** — a `connect()` call on a connected renderer disconnects it first.
-- **`disconnect()` clears the container** and cancels every signal watcher and store watcher.
+- **`disconnect()` clears the container** and cancels every atom watcher and store watcher.
 
 @xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
 

package/api/@xmachines/play-dom/classes/PlayRenderer.md

@@ -2,11 +2,11 @@
 
 # Class: PlayRenderer
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/PlayRenderer.ts#L130)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/PlayRenderer.ts#L129)
 
-PlayRenderer connects the `currentView` signal of an actor to the DOM renderer.
+PlayRenderer connects the `currentView` atom of an actor to the DOM renderer.
 
-It watches `actor.currentView` through the TC39 Signals. It renders each
+It watches `actor.currentView` through the atoms. It renders each
 `DomComponentRenderer` function into `container` on every view transition.
 `disconnect()` clears the container.
 
@@ -38,7 +38,7 @@ renderer.disconnect();
 **The controlled store mode** — you give your own `StateStore`:
 
 ```typescript
-import { createAtom } from "@xstate/store";
+import { createAtom } from "@xmachines/play-atom";
 import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
 
 const atom = createAtom({ username: "" });
@@ -64,14 +64,14 @@ new PlayRenderer(
 ): PlayRenderer;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/PlayRenderer.ts#L224)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/PlayRenderer.ts#L223)
 
 #### Parameters
 
 | Parameter   | Type                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | ----------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `container` | `HTMLElement`                                                  | The `HTMLElement` to render into. Each view transition clears it and fills it again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `actor`     | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) | The actor with the `currentView` signal. It must implement `Viewable`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `actor`     | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) | The actor with the `currentView` atom. It must implement `Viewable`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                | The map of the component renderers, usually `registryResult.registry` from `defineRegistry`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)            | The configuration. See [PlayDomOptions](../interfaces/PlayDomOptions.md): - `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. |
 
@@ -87,13 +87,13 @@ Defined in: [packages/play-dom/src/PlayRenderer.ts:224](https://gitlab.com/xmach
 connect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/PlayRenderer.ts#L240)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/PlayRenderer.ts#L239)
 
 Starts the watch of actor.currentView, and renders into the container.
-It renders the first view synchronously, then it subscribes to the signal changes.
+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 `watchSignal` subscription.
+follow the previous `connect()`, installs a second `watchAtom` subscription.
 Each view change then renders two times. Therefore this method disconnects the
 renderer first.
 
@@ -109,7 +109,7 @@ renderer first.
 disconnect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/PlayRenderer.ts#L284)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/PlayRenderer.ts#L283)
 
 Stops the watch and clears the container.
 

package/api/@xmachines/play-dom/functions/asCleanup.md

@@ -6,7 +6,7 @@
 function asCleanup<R>(release): Cleanup;
 ```
 
-Defined in: [packages/play/src/disposable.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L150)
+Defined in: [packages/play/src/disposable.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L149)
 
 Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
 
@@ -70,9 +70,8 @@ protocol adds a property, and a sealed function accepts none.
 ## Example
 
 ```ts
-export function watchSignal<T>(signal: Signal.State<T>, onValue: (v: T) => void): Cleanup {
-	const watcher = new Signal.subtle.Watcher(() => {});
-	watcher.watch(signal);
-	return asCleanup(() => watcher.unwatch(signal));
+export function watchAtom<T>(atom: Readable<T>, onValue: (v: T) => void): Cleanup {
+	const subscription = atom.subscribe(() => onValue(atom.get()));
+	return asCleanup(() => subscription.unsubscribe());
 }
 ```

package/api/@xmachines/play-dom/functions/createPlayUI.md

@@ -6,7 +6,7 @@
 function createPlayUI(registryResult, options?): MountFn;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L118)
+Defined in: [packages/play-dom/src/create-play-ui.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/create-play-ui.ts#L118)
 
 Creates the mount function of the complete DOM renderer.
 

package/api/@xmachines/play-dom/functions/createRenderer.md

@@ -6,7 +6,7 @@
 function createRenderer<C>(catalog, componentMap): (actor, container, options?) => Cleanup;
 ```
 
-Defined in: [packages/play-dom/src/create-renderer.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-renderer.ts#L88)
+Defined in: [packages/play-dom/src/create-renderer.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/create-renderer.ts#L88)
 
 Creates a DOM renderer factory from a catalog and a component map. You can use
 the factory more than one time.

package/api/@xmachines/play-dom/interfaces/CreatePlayUIOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: CreatePlayUIOptions
 
-Defined in: [packages/play-dom/src/types.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L152)
+Defined in: [packages/play-dom/src/types.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L152)
 
 The options of `createPlayUI()`, the complete DOM factory.
 
@@ -31,10 +31,10 @@ createPlayUI
 | Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                         | Defined in                                                                                                                         |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [`UIProviderOptions`](UIProviderOptions.md).[`directives`](UIProviderOptions.md#property-directives)                   | -                                                                                                                                  |
-| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| (() => `HTMLElement`) \| `null`                                                          | The optional fallback content — see [PlayDomOptions.fallback](PlayDomOptions.md#property-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: `const mount = createPlayUI(registryResult, { 	fallback: () => { 		const element = document.createElement("p"); 		element.textContent = "Loading…"; 		return element; 	}, });` An element stays correct for a factory that mounts one time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                                                                                                      | [packages/play-dom/src/types.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L176) |
+| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| (() => `HTMLElement`) \| `null`                                                          | The optional fallback content — see [PlayDomOptions.fallback](PlayDomOptions.md#property-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: `const mount = createPlayUI(registryResult, { 	fallback: () => { 		const element = document.createElement("p"); 		element.textContent = "Loading…"; 		return element; 	}, });` An element stays correct for a factory that mounts one time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                                                                                                      | [packages/play-dom/src/types.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L176) |
 | <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | -                                                                                                                                  |
 | <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | -                                                                                                                                  |
 | <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`UIProviderOptions`](UIProviderOptions.md).[`onConfirm`](UIProviderOptions.md#property-onconfirm)                     | -                                                                                                                                  |
-| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                              | The optional handler of a failure of a complete rebuild of the view. This option is NOT the same as `onRenderError`, which [UIProviderOptions](UIProviderOptions.md) 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. | [`PlayDomOptions`](PlayDomOptions.md).[`onError`](PlayDomOptions.md#property-onerror)                                  | [packages/play-dom/src/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L100) |
+| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                              | The optional handler of a failure of a complete rebuild of the view. This option is NOT the same as `onRenderError`, which [UIProviderOptions](UIProviderOptions.md) 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. | [`PlayDomOptions`](PlayDomOptions.md).[`onError`](PlayDomOptions.md#property-onerror)                                  | [packages/play-dom/src/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L100) |
 | <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Unified error handler for component render errors and action handler rejections. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Invoked for three distinct error classes: - `(error, elementType)` — when a component renderer throws synchronously during `renderSpec` - `(error, actionName)` — when an action handler rejects during `emit()` (on-event path) - `(error, actionName)` — when an action handler rejects during a `watch` binding callback When provided, suppresses the `console.error` fallback for all three error types. Forwarded into `renderSpec` as the `onRenderError` parameter and into `DomRenderContext.onRenderError` so both `emit()` and `watch` handlers route their errors through the same channel as component render errors. **Example** `renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, });`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | -                                                                                                                                  |
 | <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions for inline field validation. Each function receives `(value, args?)` and returns `true` (valid) or `false` (invalid). Functions are available to component implementations via `ctx.ctx.validationFunctions` and should be passed as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Mirrors `customFunctions` in `ValidationProvider` from the framework renderers. The DOM renderer has no automatic `ValidationProvider` tree — validation must be invoked explicitly by component implementations. **Example** `import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { validationFunctions: { isEven: (value) => typeof value === "number" && value % 2 === 0, phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)), }, }); // Inside a ComponentFn: const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => { const result = runValidationCheck( { type: "isEven", message: "must be even" }, { value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions }, ); // result.valid, result.message };`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | -                                                                                                                                  |

package/api/@xmachines/play-dom/interfaces/MountOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: MountOptions
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L50)
+Defined in: [packages/play-dom/src/create-play-ui.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/create-play-ui.ts#L50)
 
 The mount options of the `MountFn` that `createPlayUI` returns.
 
@@ -15,5 +15,5 @@ time.
 
 | Property                                 | Type         | Description                                                                                                                                                                              | Defined in                                                                                                                                         |
 | ---------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-loading"></a> `loading?` | `boolean`    | With the value `true`, the renderer stops each warning about an absent child during the ingestion of a streaming spec. It also gives `ctx.ctx.loading` to each component implementation. | [packages/play-dom/src/create-play-ui.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L62) |
-| <a id="property-store"></a> `store?`     | `StateStore` | The optional external `StateStore`, which is the controlled mode. Without it, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.   | [packages/play-dom/src/create-play-ui.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L56) |
+| <a id="property-loading"></a> `loading?` | `boolean`    | With the value `true`, the renderer stops each warning about an absent child during the ingestion of a streaming spec. It also gives `ctx.ctx.loading` to each component implementation. | [packages/play-dom/src/create-play-ui.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/create-play-ui.ts#L62) |
+| <a id="property-store"></a> `store?`     | `StateStore` | The optional external `StateStore`, which is the controlled mode. Without it, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.   | [packages/play-dom/src/create-play-ui.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/create-play-ui.ts#L56) |

package/api/@xmachines/play-dom/interfaces/PlayDomOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L23)
+Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L23)
 
 The options of `PlayRenderer`.
 
@@ -20,13 +20,13 @@ reads them at `ctx.ctx.*`.
 | Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                         | Defined in                                                                                                                         |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [`UIProviderOptions`](UIProviderOptions.md).[`directives`](UIProviderOptions.md#property-directives)                   | -                                                                                                                                  |
-| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| (() => `HTMLElement`) \| `null`                                                          | 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. [CreatePlayUIOptions.fallback](CreatePlayUIOptions.md#property-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 [PlayDomOptions.onError](#property-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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                      | [packages/play-dom/src/types.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L132) |
+| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| (() => `HTMLElement`) \| `null`                                                          | 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. [CreatePlayUIOptions.fallback](CreatePlayUIOptions.md#property-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 [PlayDomOptions.onError](#property-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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                      | [packages/play-dom/src/types.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L132) |
 | <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | -                                                                                                                                  |
-| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                 | With the value `true`, the spec is still streaming, for example from an AI provider. The renderer gives the flag to `renderSpec`. A component implementation therefore reads `ctx.ctx.loading`, and it can render a skeleton state. The flag also stops each warning about an absent child during the ingestion of the stream, because an element of a reference can still be absent from the incremental spec. This option matches the `loading` prop of the framework renderer providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                                                                                                                      | [packages/play-dom/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L54)   |
+| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                 | With the value `true`, the spec is still streaming, for example from an AI provider. The renderer gives the flag to `renderSpec`. A component implementation therefore reads `ctx.ctx.loading`, and it can render a skeleton state. The flag also stops each warning about an absent child during the ingestion of the stream, because an element of a reference can still be absent from the incremental spec. This option matches the `loading` prop of the framework renderer providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | -                                                                                                                      | [packages/play-dom/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L54)   |
 | <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | -                                                                                                                                  |
 | <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`UIProviderOptions`](UIProviderOptions.md).[`onConfirm`](UIProviderOptions.md#property-onconfirm)                     | -                                                                                                                                  |
-| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                              | The optional handler of a failure of a complete rebuild of the view. This option is NOT the same as `onRenderError`, which [UIProviderOptions](UIProviderOptions.md) 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. | -                                                                                                                      | [packages/play-dom/src/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L100) |
+| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                              | The optional handler of a failure of a complete rebuild of the view. This option is NOT the same as `onRenderError`, which [UIProviderOptions](UIProviderOptions.md) 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. | -                                                                                                                      | [packages/play-dom/src/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L100) |
 | <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Unified error handler for component render errors and action handler rejections. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Invoked for three distinct error classes: - `(error, elementType)` — when a component renderer throws synchronously during `renderSpec` - `(error, actionName)` — when an action handler rejects during `emit()` (on-event path) - `(error, actionName)` — when an action handler rejects during a `watch` binding callback When provided, suppresses the `console.error` fallback for all three error types. Forwarded into `renderSpec` as the `onRenderError` parameter and into `DomRenderContext.onRenderError` so both `emit()` and `watch` handlers route their errors through the same channel as component render errors. **Example** `renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, });`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | -                                                                                                                                  |
-| <a id="property-registryresult"></a> `registryResult?`           | [`DefineRegistryResult`](DefineRegistryResult.md)                                                         | The result of `defineRegistry`. It gives the registry and the factory of the handlers. With this option, `PlayRenderer` connects `setState` and `getState` of the `StateStore` on @xstate/store to the factory of the handlers for you. This is the preferred way, because each action then always receives a live `setState` and a live `state` on the current store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                      | [packages/play-dom/src/types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L32)   |
-| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | The optional external StateStore, for example from `xstateStoreStateStore` in @xmachines/json-render-xstate. With this option, `PlayRenderer` works in the controlled mode: it ignores `spec.state`, and this store is the single source of truth of the UI state, such as a form value. Without this option, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                      | [packages/play-dom/src/types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L42)   |
+| <a id="property-registryresult"></a> `registryResult?`           | [`DefineRegistryResult`](DefineRegistryResult.md)                                                         | The result of `defineRegistry`. It gives the registry and the factory of the handlers. With this option, `PlayRenderer` connects `setState` and `getState` of the `StateStore` on @xstate/store to the factory of the handlers for you. This is the preferred way, because each action then always receives a live `setState` and a live `state` on the current store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                      | [packages/play-dom/src/types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L32)   |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | The optional external StateStore, for example from `xstateStoreStateStore` in @xmachines/json-render-xstate. With this option, `PlayRenderer` works in the controlled mode: it ignores `spec.state`, and this store is the single source of truth of the UI state, such as a form value. Without this option, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                      | [packages/play-dom/src/types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/types.ts#L42)   |
 | <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions for inline field validation. Each function receives `(value, args?)` and returns `true` (valid) or `false` (invalid). Functions are available to component implementations via `ctx.ctx.validationFunctions` and should be passed as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Mirrors `customFunctions` in `ValidationProvider` from the framework renderers. The DOM renderer has no automatic `ValidationProvider` tree — validation must be invoked explicitly by component implementations. **Example** `import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { validationFunctions: { isEven: (value) => typeof value === "number" && value % 2 === 0, phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)), }, }); // Inside a ComponentFn: const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => { const result = runValidationCheck( { type: "isEven", message: "must be even" }, { value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions }, ); // result.valid, result.message };`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | -                                                                                                                                  |

package/api/@xmachines/play-dom/type-aliases/Cleanup.md

@@ -6,7 +6,7 @@
 type Cleanup = () => void & { [Key in DisposeKey]: () => void };
 ```
 
-Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L66)
+Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play/src/disposable.ts#L66)
 
 The release of a subscription. A caller runs it, or a scope releases it.
 
@@ -16,12 +16,12 @@ caller inside one scope writes `using` and writes no teardown at all:
 
 ```ts
 // The explicit form. It stays correct.
-const stop = watchSignal(count, render);
+const stop = watchAtom(count, render);
 stop();
 
 // The scoped form. The scope releases it, and an exception releases it too.
 {
-	using stop = watchSignal(count, render);
+	using stop = watchAtom(count, render);
 	render(count.get());
 }
 ```

package/api/@xmachines/play-dom/type-aliases/MountFn.md

@@ -6,7 +6,7 @@
 type MountFn = (actor, container, options?) => Cleanup;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L94)
+Defined in: [packages/play-dom/src/create-play-ui.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/src/create-play-ui.ts#L94)
 
 The mount function that `createPlayUI` returns.