@xmachines/docs 6.0.0 → 7.0.0

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

@@ -4,7 +4,7 @@
 
 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-6.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-7.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -15,9 +15,11 @@ pnpm add @xmachines/play-dom
 **Peer dependencies:**
 
 ```bash
-pnpm add @xmachines/core @xmachines/play @xmachines/play-atom @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
+pnpm add @xmachines/core @xmachines/play @xmachines/play-atom @xstate/store @xmachines/json-render-core@0.21.0-xm.6 @xmachines/json-render-dom@0.21.0-xm.6 @xmachines/json-render-xstate@0.21.0-xm.6
 ```
 
+The json-render packages are exact peers: install the version that this release names, `0.21.0-xm.6`.
+
 [`@xmachines/play`](../play/README.md) is the peer of [`@xmachines/play-view`](../play-view/README.md), which this package depends on. Install ONE copy of it.
 
 `@xstate/store` is the peer of [`@xmachines/play-atom`](../play-atom/README.md), and not of this
@@ -106,7 +108,7 @@ disconnect();
 
 `createRenderer` is the simplest integration path. Call it one time at module scope, with your catalog and your component map. Then call the `mount` function that it returns, one time for each pair of an actor and a container.
 
-```typescript
+```typescript fragment
 import { createRenderer, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@xmachines/json-render-core";
 
@@ -124,9 +126,9 @@ 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`, `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.
+The factory holds the factory options (`functions`, `directives`, `validationFunctions`, `navigate`, `onConfirm`, `confirmDialog`, `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
+```typescript fragment
 import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@xmachines/json-render-core";
 
@@ -161,12 +163,14 @@ disconnect();
 Use `PlayRenderer` directly when you need the explicit `connect()` and `disconnect()` control, or when you integrate the renderer into a system that controls its life itself.
 
 ```typescript
-import { PlayRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+import { PlayRenderer, type DefineRegistryResult } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
 
-// catalog, actor from the Quick Start; components/actions as in the createPlayUI example
-const registryResult = defineRegistry(catalog, { components, actions });
+declare const actor: ViewActor; // the actor of the Quick Start
+// The result of defineRegistry(catalog, { components, actions }), as in the createPlayUI example
+declare const registryResult: DefineRegistryResult;
 
-// container: your mount element, e.g. document.getElementById("app")!
+const container = document.getElementById("app")!;
 const renderer = new PlayRenderer(container, actor, registryResult.registry, { registryResult });
 
 renderer.connect();
@@ -174,16 +178,21 @@ renderer.connect();
 renderer.disconnect();
 ```
 
-**Controlled store mode.** Give the renderer an external `StateStore`. The renderer then shares the state with the other parts of your application:
+**Controlled store mode.** Give the renderer an external `StateStore`. The renderer then shares the state with the other parts of your application. The tree lives as long as the store, so a new `viewKey` updates the tree in place, as the framework renderers do:
 
 ```typescript
+import { PlayRenderer, type DefineRegistryResult } from "@xmachines/play-dom";
 import { createAtom } from "@xmachines/play-atom";
 import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
+import type { ViewActor } from "@xmachines/play-view";
+
+declare const actor: ViewActor; // the actor of the Quick Start
+declare const registryResult: DefineRegistryResult; // from the previous example
 
 const atom = createAtom<Record<string, unknown>>({ username: "" });
 const store = xstateStoreStateStore({ atom });
 
-// container, actor, registryResult from the previous example
+const container = document.getElementById("app")!;
 const renderer = new PlayRenderer(container, actor, registryResult.registry, {
 	registryResult,
 	store,
@@ -200,6 +209,10 @@ Every entry point (`createPlayUI` and `PlayRenderer`) accepts the same UI-provid
 This option permits a dynamic prop value of the form `{ "$computed": "name", "args": {...} }` in a spec. Each function receives the resolved `args` object, and it returns the computed value.
 
 ```typescript
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
+
 const mount = createPlayUI(registryResult, {
 	functions: {
 		fullName: (args) => `${args.first} ${args.last}`,
@@ -208,7 +221,7 @@ const mount = createPlayUI(registryResult, {
 });
 ```
 
-Without `functions`, every `$computed` expression resolves to `undefined`. Nothing throws, and the old behavior stays.
+Without `functions`, every `$computed` expression resolves to `undefined`, and nothing throws.
 
 ### `validationFunctions` — custom field validation
 
@@ -217,7 +230,12 @@ This option gives the named check functions for a field check inside a component
 The DOM renderer has no `ValidationProvider` tree, and in this it is different from the framework renderers. Each component must call the check itself, with `runValidationCheck` or `runValidation` from `@xmachines/json-render-core`. Give `ctx.ctx.validationFunctions` to the call as `customFunctions`.
 
 ```typescript
-import { runValidationCheck } from "@xmachines/json-render-core";
+import { createPlayUI, schema } from "@xmachines/play-dom";
+import type { ComponentFn, DefineRegistryResult } from "@xmachines/play-dom";
+import { defineCatalog, runValidationCheck } from "@xmachines/json-render-core";
+import { z } from "zod";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
 
 const mount = createPlayUI(registryResult, {
 	validationFunctions: {
@@ -226,12 +244,17 @@ const mount = createPlayUI(registryResult, {
 	},
 });
 
-// Inside a ComponentFn (catalog from the Quick Start):
-const Login: ComponentFn<typeof catalog, "Login"> = ({ ctx }) => {
+const catalog = defineCatalog(schema, {
+	components: { Login: { props: z.object({ title: z.string() }) } },
+	actions: {},
+});
+
+// Inside a ComponentFn:
+const Login: ComponentFn<typeof catalog, "Login"> = (ctx) => {
 	const someValue = 42; // the value to validate, e.g. read from an input
 	const result = runValidationCheck(
 		{ type: "isEven", message: "must be even" },
-		{ value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions },
+		{ value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions ?? {} },
 	);
 	// result.valid, result.message
 	return null;
@@ -243,7 +266,13 @@ const Login: ComponentFn<typeof catalog, "Login"> = ({ ctx }) => {
 The renderer calls this callback when an action binding resolves with `onSuccess: { navigate: "/path" }`. The callback receives the resolved path string as its only argument. Use it with every router:
 
 ```typescript
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
+
 // React Router / TanStack Router / any push-based router:
+declare const myRouter: { push(path: string): void };
+
 const mount = createPlayUI(registryResult, {
 	navigate: (path) => myRouter.push(path),
 });
@@ -266,48 +295,75 @@ With a spec binding:
 
 A component implementation can also read the function at `ctx.ctx.navigate`. Use this when a navigation must start outside an action binding.
 
+### `onConfirm` and `confirmDialog` — the bindings with `confirm`
+
+An action binding with a `confirm` field waits for the user. Without `onConfirm`, the default confirm dialog of `@xmachines/json-render-dom` shows the binding on `document.body`, as the `ConfirmDialog` of the framework renderers does. The action runs when the user confirms, and a cancel runs nothing and throws nothing. `disconnect()` and a new view cancel a confirmation that waits.
+
+- Give `onConfirm` to decide each binding in your own code. It receives the confirm config and the resolved action, and it returns `true`, or a promise of `true`, to run the action.
+- Give `confirmDialog: false` to turn the default dialog off. The binding then waits for a component of your catalog, which reads and answers it through `ctx.ctx.confirmation`.
+
+```typescript
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
+
+const mount = createPlayUI(registryResult, {
+	onConfirm: (confirm) => window.confirm(`${confirm.title}\n${confirm.message}`),
+});
+```
+
 ### `onRenderError` — unified error handler
 
-The handler receives `(error, name)` for three different classes of error:
+The inner renderer calls the handler with `(error, name, info)` one time for each failure that it reports. `info.kind` names the failure:
 
-- **A component render error** — a `ComponentFn` throws synchronously during `renderSpec`. `name` is then the catalog component name, for example `"Home"`.
-- **An action handler rejection on the emit path** — an `ActionFn` throws, or it returns a rejected promise, during `emit()`. `name` is then the catalog action name, for example `"submitForm"`.
-- **An action handler rejection on the watch path** — an `ActionFn` rejects during a `watch` binding callback. `name` is then the catalog action name.
+- **`"element"`** — a `ComponentFn` below the root throws, or an effect of it throws. `name` is the catalog component name, for example `"Home"`. The element shows nothing until a new version of it arrives.
+- **`"props"` and `"visible"`** — a prop expression or the `visible` condition of a child throws. The boundary of the parent shows nothing, and `name` is the type of the parent.
+- **`"action"` and `"watch"`** — an `on` chain or a `watch` chain fails, for example an `ActionFn` that throws or rejects. `name` is the catalog action name, for example `"submitForm"`. The chain stops, and the element stays.
+- **`"root"`** — the component, a prop, or the `visible` condition of the root throws. No view stays on the screen, so `PlayRenderer` also contains the failure as a failure of the view: see [`onError`](#onerror-the-failure-of-a-complete-rebuild).
+
+`info.key` and `info.type` name the element, and `info.action` names the action of a chain. A handler with the two parameters `(error, name)` stays valid.
 
 ```typescript
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
+
+// Sentry: your error tracking client
+declare const Sentry: { captureException(error: unknown, context?: object): void };
+
 const mount = createPlayUI(registryResult, {
-	onRenderError: (err, name) => {
+	onRenderError: (err, name, info) => {
 		// Route to your application's error tracking
-		Sentry.captureException(err, { extra: { name } });
+		Sentry.captureException(err, { extra: { name, kind: info.kind, key: info.key } });
 	},
 });
 ```
 
-The order of the arguments is the same as in the `RenderErrorHandler` type of `@xmachines/json-render-core`: **the error first, the name second**. The framework renderers (`@xmachines/json-render-solid` and `@xmachines/json-render-react`) use the same order.
+The type is `OnRenderError` of `@xmachines/json-render-core`, and this package exports it with `RenderErrorInfo` and `RenderErrorKind`. The framework renderers use the same handler, and they contain a failure of the root in the same way.
 
-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.
+Without `onRenderError`, the renderer reads the handler that `defineRegistry(catalog, { onRenderError })` put on the registry. Without that handler too, it writes one `console.error` line for each failure, such as `[json-render] element error in <Home> "home":`, and then the error. No exception goes to the caller, and no promise rejection stays unhandled. A failure of the root gets no such line: the containment reports it to `onError`, or to its own console line. A handler that throws gives its error to `reportError` of the page one time.
 
-### The renderer contains a failed rebuild — a change of behaviour in 2.3.0
+### The renderer contains a failed rebuild
 
 **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 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,
-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 renderer contains a view that fails the rebuild 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()` never sees that `catch` run.
 
 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.
+a framework is not an option that a caller turns off. play-dom follows the same rule.
 
 **To escalate a failure, raise it from a task of your own.** The example imports `rethrowLater` from [`@xmachines/core/utils`](../core/README.md). Install that package next to this one, because your code imports it and a package manager such as pnpm does not let your code import a package that it does not declare:
 
 ```typescript
 import { rethrowLater } from "@xmachines/core/utils";
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
+
+declare function reportToSentry(error: unknown): void; // your error tracking
 
 const mount = createPlayUI(registryResult, {
 	onError: (err) => {
@@ -321,13 +377,13 @@ A throw that leaves the handler itself reaches no caller. The renderer contains
 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
+### `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.
+`onRenderError` covers one element: the inner renderer contains a render error of a component below the root, and a rejection of an action handler, per element, and the rest of the view stays. A failure of the ROOT leaves no view: its component throws, or a `$computed` function throws during the resolution of a prop of the root, for example. The resolution of the store of the view can fail too, when an accessor of `spec.state` throws.
 
-`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.
+`onError` receives such a failure, one time. A failure of the root reaches `onRenderError` too, with `info.kind` `"root"`, so a host that sends both handlers to one tool skips that kind in one of them. The renderer contains the failure 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, and a bad initial view does not make `connect()` throw.
 
-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.
+A write of the store takes the same path. The renderer shows a write at its commit point, a microtask after the write, and it resolves the props of every element that the write touched there. A `$computed` function of the root that throws on the new state fails the root. 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.
 
@@ -336,6 +392,12 @@ A reset of `PlayRenderer` belongs to ONE connection. `connect()` starts a connec
 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
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+
+declare const registryResult: DefineRegistryResult; // from defineRegistry(catalog, ...)
+
+declare function reportToSentry(error: unknown): void; // your error tracking
+
 const mount = createPlayUI(registryResult, {
 	onError: (err) => reportToSentry(err),
 	fallback: document.getElementById("crashed")!,
@@ -350,16 +412,26 @@ const mount = createPlayUI(registryResult, {
 
 **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:
+A component implementation can also read the handler at `ctx.ctx.onRenderError`. A component therefore sends its own internal errors through the same channel, with the `info` of the failure:
 
 ```typescript
-// catalog from the Quick Start; doSomethingRisky: your render logic that may throw
-const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
+import { schema, type ComponentFn } from "@xmachines/play-dom";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+	components: { Home: { props: z.object({ title: z.string() }) } },
+	actions: {},
+});
+
+declare function doSomethingRisky(): HTMLElement; // your render logic that may throw
+
+const Home: ComponentFn<typeof catalog, "Home"> = (ctx) => {
 	try {
 		const el = doSomethingRisky();
 		return el;
 	} catch (err) {
-		ctx.ctx.onRenderError?.(err, "Home");
+		ctx.ctx.onRenderError?.(err, "Home", { kind: "element", type: "Home" });
 		return null;
 	}
 };
@@ -380,30 +452,32 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 
 ### 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`, 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?) → () => void`. `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                                                                                      |
+| 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?) → () => void`. `createPlayUI` returns one, and a consumer may write one            |
+| `UIProviderOptions`      | Shared options: `functions`, `directives`, `validationFunctions`, `navigate`, `onRenderError`, `onConfirm`, `confirmDialog` |
+| `OnRenderError`          | The `(error, name, info)` handler of `onRenderError`. `RenderErrorInfo` and `RenderErrorKind` type its `info`               |
+| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                                                             |
+| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                                                   |
+| `DomSchema`              | Type of the `schema` export                                                                                                 |
 
 ## Rendering Behavior
 
 - **The first render is synchronous** — the renderer fills the container before `connect()` returns.
 - **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 store write shows at its commit point** — the inner renderer renders the writes of one task together, in a microtask after the first write. Code that reads the DOM right after a write waits for that microtask.
 - **A second `connect()` is safe** — a `connect()` call on a connected renderer disconnects it first.
-- **`disconnect()` clears the container** and cancels every atom watcher and store watcher.
+- **`disconnect()` clears the container** and cancels every atom watcher and store watcher. It also stops a store write that waits for its commit point, and it cancels a confirmation that waits.
 
 @xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
 
@@ -444,7 +518,9 @@ The public API has two layers:
 - [EventHandle](interfaces/EventHandle.md)
 - [FieldValidationState](interfaces/FieldValidationState.md)
 - [MountOptions](interfaces/MountOptions.md)
+- [PassOptions](interfaces/PassOptions.md)
 - [PlayDomOptions](interfaces/PlayDomOptions.md)
+- [RenderErrorInfo](interfaces/RenderErrorInfo.md)
 - [RenderSpecOptions](interfaces/RenderSpecOptions.md)
 - [UIProviderOptions](interfaces/UIProviderOptions.md)
 - [ValidationRegistry](interfaces/ValidationRegistry.md)
@@ -463,7 +539,9 @@ The public API has two layers:
 - [DomRegistry](type-aliases/DomRegistry.md)
 - [DomSchema](type-aliases/DomSchema.md)
 - [MountFn](type-aliases/MountFn.md)
+- [OnRenderError](type-aliases/OnRenderError.md)
 - [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
+- [RenderErrorKind](type-aliases/RenderErrorKind.md)
 - [SetState](type-aliases/SetState.md)
 
 ## Variables

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

@@ -2,7 +2,7 @@
 
 # Class: PlayRenderer
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/PlayRenderer.ts#L127)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/PlayRenderer.ts#L133)
 
 PlayRenderer connects the `currentView` atom of an actor to the DOM renderer.
 
@@ -17,7 +17,7 @@ Every option of `PlayDomOptions`, which extends `UIProviderOptions`, goes into
 - `directives` — your own dynamic values with a `$` prefix, from `defineDirective`. The renderer resolves them with the props
 - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`
 - `navigate` — the navigation callback. The renderer calls it for an `onSuccess: { navigate: "..." }` action binding
-- `onRenderError` — the renderer calls it with `(error, name)` for a component render error and for an action handler rejection
+- `onRenderError` — the renderer calls it with `(error, name, info)` for each failure that the inner renderer reports
 
 **The preferred use, with `registryResult`:**
 
@@ -64,16 +64,16 @@ new PlayRenderer(
 ): PlayRenderer;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/PlayRenderer.ts#L221)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:246](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/PlayRenderer.ts#L246)
 
 #### 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` 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. |
+| 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` 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, info)` handler of each failure that the inner renderer reports. It stops the `[json-render]` console line. - `onError` — the `(error, reset)` handler of a failure of the view: a failure of the root, or of a complete rebuild. The renderer contains such a failure always, and this option says where the report goes. - `fallback` — the element to show for every null view, and after a contained failure. |
 
 #### Returns
 
@@ -87,13 +87,13 @@ Defined in: [packages/play-dom/src/PlayRenderer.ts:221](https://gitlab.com/xmach
 connect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/PlayRenderer.ts#L237)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:262](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/PlayRenderer.ts#L262)
 
 Starts the watch of actor.currentView, and renders into the container.
 It renders the first view synchronously, then it subscribes to the atom changes.
 
 A `connect()` call on a connected renderer, where a `disconnect()` call did not
-follow the previous `connect()`, installs a second `watchAtom` subscription.
+follow the previous `connect()`, installs a second subscription of the view.
 Each view change then renders two times. Therefore this method disconnects the
 renderer first.
 
@@ -109,7 +109,7 @@ renderer first.
 disconnect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:281](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/PlayRenderer.ts#L281)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/PlayRenderer.ts#L292)
 
 Stops the watch and clears the container.
 

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:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/create-play-ui.ts#L110)
+Defined in: [packages/play-dom/src/create-play-ui.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/create-play-ui.ts#L112)
 
 Creates the mount function of the complete DOM renderer.
 
@@ -16,10 +16,10 @@ 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. - `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. |
+| 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, info)` handler of each failure that the inner renderer reports. - `onConfirm` — the hook that decides each binding with `confirm`. Without it, the default confirm dialog shows the binding. - `confirmDialog` — `false` turns the default confirm dialog off. The binding then waits for `ctx.confirmation`. - `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
 

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

@@ -6,7 +6,7 @@
 function createRenderer<C>(catalog, componentMap): (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-renderer.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/create-renderer.ts#L87)
+Defined in: [packages/play-dom/src/create-renderer.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/create-renderer.ts#L87)
 
 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/functions/renderSpec.md

@@ -30,8 +30,9 @@ built by `defineRegistry` — this function only orchestrates the traversal.
 
 `Node` \| `null`
 
-The root DOM `Node`, or `null` if the root is invisible
-or has no registered renderer.
+The root DOM `Node`, or `null` if the root is invisible,
+has no registered renderer, or fails. A failure goes to
+`onRenderError`, or to `console.error`.
 
 ## Remarks
 

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

@@ -13,12 +13,12 @@ Defined in: `@xmachines/json-render-dom`
 
 ## Properties
 
-| Property                                  | Type                                          | Description                                                                                                                                                                             | Defined in |
-| ----------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions.                                                                                                        | -          |
-| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list (the default slot).                                                                                                                | -          |
-| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                                                                                                                               | -          |
-| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                                                                                                                                  | -          |
-| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map.                                                                                                                        | -          |
-| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                                                                                                                                 | -          |
-| <a id="property-slots"></a> `slots?`      | `Record`\<`string`, `Node`[]\>                | Rendered nodes per named slot from the spec's `slots` map, or `undefined` when the element fills no named slot. Mirrors `slots` in @xmachines/json-render-react's ComponentRenderProps. | -          |
+| Property                                  | Type                                          | Description                                                                                                                                                                                                                                                    | Defined in |
+| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions.                                                                                                                                                                               | -          |
+| <a id="property-children"></a> `children` | `Node`[]                                      | The child nodes of the spec's `children` list (the default slot). A getter: the children render at the first read, one time. A child that the component never reads does not mount, and a parameter that destructures `children` reads it at once.             | -          |
+| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                                                                                                                                                                                                      | -          |
+| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                                                                                                                                                                                                         | -          |
+| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map.                                                                                                                                                                                               | -          |
+| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                                                                                                                                                                                                        | -          |
+| <a id="property-slots"></a> `slots?`      | `Record`\<`string`, `Node`[]\>                | The nodes of each named slot of the spec's `slots` map, or `undefined` when the element fills no named slot. Each slot is a getter that renders at its first read, as `children` does. Mirrors `slots` in @xmachines/json-render-react's ComponentRenderProps. | -          |