@xmachines/docs 2.2.0 → 4.0.0

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

@@ -4,7 +4,7 @@
 
 Vanilla DOM renderer for XMachines Play architecture with signal-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-2.2.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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -15,14 +15,15 @@ pnpm add @xmachines/play-dom
 **Peer dependencies:**
 
 ```bash
-pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
+pnpm add @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
 ```
 
 ## Quick Start
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withView } from "@xmachines/play-xstate/view";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { createMachine } from "xstate";
 import { z } from "zod";
@@ -82,7 +83,8 @@ const machine = createMachine({
 		},
 	},
 });
-const actor = definePlayer({ machine })();
+// `mount` needs the view capability
+const actor = definePlayer({ machine, actor: compose(PlayerActor, withView) })();
 actor.start();
 
 // 5. Mount when actor and container are ready
@@ -116,7 +118,7 @@ disconnect();
 
 Use `createPlayUI` when you need a render error handler, a fallback element, a navigation integration, a computed function, or a custom check. Use it also when your code needs the `registryResult` value, for example for `executeAction`.
 
-The factory holds the factory options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and it applies them on every `mount()` call. Give the mount options (`store` and `loading`) to `mount()` itself.
+The factory holds the factory options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, `onError`, and `fallback`) from the moment of its creation, and it applies them on every `mount()` call. Give the mount options (`store` and `loading`) to `mount()` itself.
 
 ```typescript
 import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
@@ -279,6 +281,69 @@ The order of the arguments is the same as in the `RenderErrorHandler` type of `@
 
 Without `onRenderError`, the renderer writes all three types of error to `console.error`, then stops them. No exception goes to the caller, and no promise rejection stays unhandled.
 
+### The renderer contains a failed rebuild — a change of behaviour in 2.3.0
+
+**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
+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,
+and no option turns it off. The renderer clears the container, it shows the `fallback`,
+and `mount()` returns normally. A host that shows its own error page from a `catch` around
+`mount()` sees that `catch` never again.
+
+The four framework renderers contain a failed render always, because an error boundary of
+a framework is not an option that a caller turns off. This change puts play-dom on the
+same rule.
+
+**To escalate a failure, raise it from a task of your own:**
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	onError: (err) => {
+		reportToSentry(err);
+		queueMicrotask(() => {
+			throw err; // the page keeps its own global handler
+		});
+	},
+});
+```
+
+A throw that leaves the handler itself reaches no caller. The renderer contains it and
+writes it to `console.error`, exactly as the four framework renderers do. The five hold
+this one rule, so a host learns it one time and writes the same handler for each of them.
+
+### `onError` — the failure of a complete rebuild
+
+`onRenderError` covers one element: the inner renderer contains a render error of a component, and a rejection of an action handler, per element, and the rebuild continues. Some failures escape that boundary — a `$computed` function that throws during the resolution of a prop, for example — and they abort the complete rebuild.
+
+`onError` receives such a failure. The renderer contains it 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.
+
+The second parameter is the **reset**, for a retry that the host starts. It renders the view that the actor holds at the moment of the call, so a retry cannot rewind the screen to the view that failed. A reset that the host calls from inside the handler does nothing, because no input changed between the two attempts, and a reset after the provider goes away does nothing. The five renderers hold the same three rules.
+
+A reset of `PlayRenderer` 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 the 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.
+
+A fourth rule holds in all five: each of them CONTAINS a handler that throws, and writes the throw to `console.error`. A host that must escalate raises the failure from a task of its own, as the section above shows.
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	onError: (err) => reportToSentry(err),
+	fallback: document.getElementById("crashed")!,
+});
+```
+
+`createPlayUI` adds the parity with the framework providers: the renderer contains the failure, and it appends the `fallback` to the container that the failed rebuild left clear. A later view that renders clears the container again, which removes the fallback.
+
+`onError` says WHERE the report goes, and `fallback` says what the empty container shows. Neither option turns the containment on. Without `onError` the renderer writes the contained error to `console.error`, in the same way as it does for a component that throws without an `onRenderError` handler. Give `onError` to send the failure to your own observability tool instead.
+
+**One fallback element belongs to one mount.** `appendChild` moves a node. Two mounts of the same factory therefore take the element from each other on every null view, and the container of the first one goes empty without a notice. Build one element for each `mount()` call.
+
+**A `fallback` producer that throws is contained too — on a null view and after a failed rebuild alike — and it reports to `console.error` and NOT to `onError`.** After a failed rebuild the renderer calls the producer from inside the containment of the view, so a second trip through `onError` would report the failure of your fallback as a failure of the view. The container stays empty, and the renderer renders the next view that works.
+
 A component implementation can also read the handler at `ctx.ctx.onRenderError`. A component therefore sends its own internal errors through the same channel:
 
 ```typescript
@@ -298,55 +363,44 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 
 ### XMachines Layer
 
-| Export                                   | Kind     | Description                                                                       |
-| ---------------------------------------- | -------- | --------------------------------------------------------------------------------- |
-| `createRenderer(catalog, components)`    | function | The one-call factory. It returns `mount(actor, container, options?) → disconnect` |
-| `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()`               |
+| 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`     |
 
 ### Key Types
 
-| Type                     | Description                                                                                   |
-| ------------------------ | --------------------------------------------------------------------------------------------- |
-| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                      |
-| `ComponentContext<C, K>` | The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`       |
-| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                          |
-| `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound` |
-| `SetState`               | State updater: `(prev => next) => void`                                                       |
-| `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`            |
-| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`                                      |
-| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback`                     |
-| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                           |
-| `MountFn`                | The mount function that `createPlayUI` returns: `(actor, container, options?) → disconnect`   |
-| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`               |
-| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                               |
-| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                     |
-| `DomSchema`              | Type of the `schema` export                                                                   |
-| `ComputedFunction`       | The type of a named compute function for the `functions` option                               |
+| Type                     | Description                                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                                      |
+| `ComponentContext<C, K>` | The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`                       |
+| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                                          |
+| `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound`                 |
+| `SetState`               | State updater: `(prev => next) => void`                                                                       |
+| `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`                            |
+| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`, adds `fallback` and `onError`                       |
+| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback` and `onError`                       |
+| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                                           |
+| `MountFn`                | The mount: `(actor, container, options?) → Cleanup`. `createPlayUI` returns one, and a consumer may write one |
+| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`                               |
+| `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`                                                    |
 
 ## 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.
-- **A null view** clears the container. The renderer can show a `fallback` element on the first mount, when the view is `null`. It does **not** add that element again when the view returns to `null` after a view that was not null.
+- **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.
 
-## Testing
-
-```bash
-# Run all tests (jsdom environment)
-pnpm test
-
-# Run with coverage
-pnpm run test:coverage
-```
-
-The tests are in `test/`. They use [Vitest](https://vitest.dev/) in a jsdom environment. The coverage thresholds are 80% for lines, functions, branches, and statements.
-
 @xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
 
 The public API has two layers:
@@ -397,6 +451,7 @@ The public API has two layers:
 - [Actions](type-aliases/Actions.md)
 - [BaseComponentProps](type-aliases/BaseComponentProps.md)
 - [CatalogHasActions](type-aliases/CatalogHasActions.md)
+- [Cleanup](type-aliases/Cleanup.md)
 - [ComponentFn](type-aliases/ComponentFn.md)
 - [ComponentRegistry](type-aliases/ComponentRegistry.md)
 - [ConfirmHandler](type-aliases/ConfirmHandler.md)
@@ -414,6 +469,7 @@ The public API has two layers:
 
 ## Functions
 
+- [asCleanup](functions/asCleanup.md)
 - [createPlayUI](functions/createPlayUI.md)
 - [createRenderer](functions/createRenderer.md)
 - [createValidationRegistry](functions/createValidationRegistry.md)

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

@@ -2,7 +2,7 @@
 
 # Class: PlayRenderer
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/PlayRenderer.ts#L72)
+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)
 
 PlayRenderer connects the `currentView` signal of an actor to the DOM renderer.
 
@@ -60,19 +60,20 @@ new PlayRenderer(
    container,
    actor,
    registry,
-   options?): PlayRenderer;
+   options?
+): PlayRenderer;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/PlayRenderer.ts#L130)
+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)
 
 #### Parameters
 
-| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | The `HTMLElement` to render into. Each view transition clears it and fills it again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | The actor with the `currentView` signal. 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. |
+| 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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. |
 
 #### Returns
 
@@ -86,7 +87,7 @@ Defined in: [packages/play-dom/src/PlayRenderer.ts:130](https://gitlab.com/xmach
 connect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/PlayRenderer.ts#L146)
+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)
 
 Starts the watch of actor.currentView, and renders into the container.
 It renders the first view synchronously, then it subscribes to the signal changes.
@@ -108,7 +109,7 @@ renderer first.
 disconnect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/PlayRenderer.ts#L155)
+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)
 
 Stops the watch and clears the container.
 

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

@@ -0,0 +1,78 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / asCleanup
+
+# Function: asCleanup()
+
+```ts
+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)
+
+Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
+
+The function comes back as itself, with [DISPOSE](../../play/index/variables/DISPOSE.md) added. Nothing wraps it, so
+the identity of the release holds: a caller that compares two releases, or that puts
+one in a `Set`, sees what it saw before this protocol existed.
+
+The release therefore must be idempotent. A scope releases the value one time, but a
+caller that runs the function AND lets the scope end runs it two times. Every release
+of this workspace already accepts that, because a teardown that runs two times is
+older than this protocol.
+
+The release must be synchronous. `Disposable` and not `AsyncDisposable`: a
+`Disposable` serves `using` AND `await using`, because `await using` falls back to
+`Symbol.dispose`, while an `AsyncDisposable` raises a TypeError under a plain `using`
+and forces every holder into an async function. Nothing in this workspace releases
+asynchronously. An `AsyncCleanup` can arrive the day something does.
+
+The `R extends void | undefined` bound is what holds that line. A plain `() => void`
+parameter would ACCEPT `async () => {}`, because TypeScript lets a function that
+returns a value stand where one returning `void` is wanted. The promise would then go
+on the floor: the scope releases, the release looks finished, and the work runs later
+with nobody able to await it. The bound rejects that at the call, and it rejects a
+release that returns any other value as well.
+
+The bound holds where the compiler knows the return type. It cannot hold where the
+caller erased it: `R` infers `any` for a release typed `any`, such as a bare
+`vi.fn()`, and `any` satisfies every constraint. A release declared `() => void` whose
+body is async passes for the same reason — the declaration, and not the body, is what
+the call site sees. Write the release inline, or type it, and the bound applies.
+
+The release lands under [DISPOSE](../../play/index/variables/DISPOSE.md) and, when the two differ, under the
+`Symbol.dispose` that exists at the CALL. `DISPOSE` resolves when the module evaluates,
+so a polyfill that installs the well-known symbol later would otherwise leave the
+release on the registered key while a downlevelled `using` reads the well-known one.
+Writing both closes that window for every release this function publishes.
+
+## Type Parameters
+
+| Type Parameter                      |
+| ----------------------------------- |
+| `R` _extends_ `void` \| `undefined` |
+
+## Parameters
+
+| Parameter | Type      | Description                                                                                                                                                                                                         |
+| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `release` | () => `R` | The release to publish. It must return nothing. The function is changed in place, so pass a function that this release owns: a shared or module-level function becomes a `Disposable` for every other holder of it. |
+
+## Returns
+
+[`Cleanup`](../type-aliases/Cleanup.md)
+
+The same function, now also a `Disposable`.
+
+## Throws
+
+TypeError - When the release is frozen or is otherwise not extensible. The
+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));
+}
+```

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:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/create-play-ui.ts#L95)
+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)
 
 Creates the mount function of the complete DOM renderer.
 
@@ -16,13 +16,13 @@ and a container.
 
 ## Parameters
 
-| Parameter        | Type                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ---------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registryResult` | [`DefineRegistryResult`](../interfaces/DefineRegistryResult.md) | The result of `defineRegistry()`. It gives the registry and the factory of the handlers, which it builds late.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `options`        | [`CreatePlayUIOptions`](../interfaces/CreatePlayUIOptions.md)   | The factory configuration. See [CreatePlayUIOptions](../interfaces/CreatePlayUIOptions.md): - `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. - `fallback` — the element to show when the first view of the actor is `null`. |
+| Parameter        | Type                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `registryResult` | [`DefineRegistryResult`](../interfaces/DefineRegistryResult.md) | The result of `defineRegistry()`. It gives the registry and the factory of the handlers, which it builds late.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `options`        | [`CreatePlayUIOptions`](../interfaces/CreatePlayUIOptions.md)   | The factory configuration. See [CreatePlayUIOptions](../interfaces/CreatePlayUIOptions.md): - `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. - `onError` — the `(error, reset)` handler of a failure of a complete rebuild. The renderer contains such a failure always, and this option says where the report goes. - `fallback` — the content to show when the view of the actor is `null`, and after a contained failure of a rebuild. Give a FUNCTION when the factory mounts more than one time, so that each renderer owns its own element. |
 
 ## Returns
 
 [`MountFn`](../type-aliases/MountFn.md)
 
-The `MountFn`: `(actor, container, mountOptions?) → disconnect`
+The [MountFn](../type-aliases/MountFn.md): `(actor, container, mountOptions?) → disconnect`

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

@@ -3,10 +3,10 @@
 # Function: createRenderer()
 
 ```ts
-function createRenderer<C>(catalog, componentMap): (actor, container, options?) => () => void;
+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/v2.2.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/v4.0.0/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.
@@ -31,7 +31,7 @@ the PlayRenderer in one call, and it returns a `disconnect` cleanup function.
 
 A `mount` function. It accepts `(actor, container, options?)`, and it returns `disconnect`.
 
-(`actor`, `container`, `options?`) => () => `void`
+(`actor`, `container`, `options?`) => [`Cleanup`](../type-aliases/Cleanup.md)
 
 ## Remarks
 

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

@@ -2,7 +2,7 @@
 
 # Interface: CreatePlayUIOptions
 
-Defined in: [packages/play-dom/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/types.ts#L69)
+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)
 
 The options of `createPlayUI()`, the complete DOM factory.
 
@@ -11,6 +11,11 @@ This type extends [UIProviderOptions](UIProviderOptions.md), which gives `functi
 holds all of them from the moment of its creation, and it gives them to
 `PlayRenderer` on every `mount()` call.
 
+It also takes [PlayDomOptions.onError](PlayDomOptions.md#property-onerror), which the factory forwards without a
+change: `PlayRenderer` owns it, and it receives every failure of a rebuild that the
+renderer contains. Read that entry for the complete rule. `fallback` below says what
+the factory adds to [PlayDomOptions.fallback](PlayDomOptions.md#property-fallback).
+
 This type is parallel to the props of `PlayUIProvider` in the framework renderers.
 
 ## See
@@ -19,16 +24,17 @@ createPlayUI
 
 ## Extends
 
-- [`UIProviderOptions`](UIProviderOptions.md)
+- [`UIProviderOptions`](UIProviderOptions.md).`Pick`\<[`PlayDomOptions`](PlayDomOptions.md), `"onError"`\>
 
 ## Properties
 
-| 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` \| `null`                                                                                   | The optional fallback element. The factory shows it when `currentView` is `null` on the **first mount** only. The factory appends the fallback directly after `mount()`, when the container is empty at that moment, which means that the first view of the actor is `null`. **Limitation:** when the view of the actor becomes `null` after the mount, the renderer clears the container, and it does NOT append this fallback again. For a dynamic fallback, which follows a null view after a view that was not null, use `PlayRenderer` directly and wrap the `actor.currentView` signal to add the fallback content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                                                                                                      | [packages/play-dom/src/types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/types.ts#L82) |
-| <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-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) | -                                                                                                                                |
+| 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-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-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) | -                                                                                                                                  |