@xmachines/docs 6.1.0 → 7.1.0

package/api/@xmachines/play-atom/interfaces/Readable.md

@@ -2,7 +2,7 @@
 
 # Interface: Readable\<T\>
 
-Defined in: [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L58)
+Defined in: [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L58)
 
 The read side of an atom
 
@@ -28,9 +28,9 @@ show(createAtom("ready")); // "ready"
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `T`            |
+| Type Parameter                    |
+| --------------------------------- |
+| <a id="type-parameter-t"></a> `T` |
 
 ## Methods
 
@@ -40,7 +40,7 @@ show(createAtom("ready")); // "ready"
 get(): T;
 ```
 
-Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L59)
+Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L59)
 
 #### Returns
 
@@ -56,7 +56,7 @@ Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1
 subscribe(observer): AtomSubscription;
 ```
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L60)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L60)
 
 ##### Parameters
 
@@ -78,7 +78,7 @@ subscribe(
 ): AtomSubscription;
 ```
 
-Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L61)
+Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L61)
 
 ##### Parameters
 

package/api/@xmachines/play-atom/interfaces/ReadonlyAtom.md

@@ -2,7 +2,7 @@
 
 # Interface: ReadonlyAtom\<T\>
 
-Defined in: [types.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L97)
+Defined in: [types.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L97)
 
 The computed atom. It evaluates late, and it memoizes the result
 
@@ -31,9 +31,9 @@ console.log(doubled.get()); // 10 (from the memory, with no new computation)
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `T`            |
+| Type Parameter                    |
+| --------------------------------- |
+| <a id="type-parameter-t"></a> `T` |
 
 ## Methods
 
@@ -43,7 +43,7 @@ console.log(doubled.get()); // 10 (from the memory, with no new computation)
 get(): T;
 ```
 
-Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L59)
+Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L59)
 
 #### Returns
 
@@ -63,7 +63,7 @@ Defined in: [types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1
 subscribe(observer): AtomSubscription;
 ```
 
-Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L60)
+Defined in: [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L60)
 
 ##### Parameters
 
@@ -89,7 +89,7 @@ subscribe(
 ): AtomSubscription;
 ```
 
-Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L61)
+Defined in: [types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L61)
 
 ##### Parameters
 

package/api/@xmachines/play-atom/type-aliases/AnyAtom.md

@@ -6,7 +6,7 @@
 type AnyAtom = BaseAtom<unknown>;
 ```
 
-Defined in: [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L129)
+Defined in: [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L129)
 
 An atom of an unknown value type
 

package/api/@xmachines/play-atom/type-aliases/AsyncAtomState.md

@@ -17,7 +17,7 @@ type AsyncAtomState<TData, TError> =
 	  };
 ```
 
-Defined in: [types.ts:157](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/types.ts#L157)
+Defined in: [types.ts:157](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/types.ts#L157)
 
 The state of an atom that reads a promise
 
@@ -26,7 +26,7 @@ you `data` or `error`.
 
 ## Type Parameters
 
-| Type Parameter | Default type |
-| -------------- | ------------ |
-| `TData`        | -            |
-| `TError`       | `unknown`    |
+| Type Parameter                              | Default type |
+| ------------------------------------------- | ------------ |
+| <a id="type-parameter-tdata"></a> `TData`   | -            |
+| <a id="type-parameter-terror"></a> `TError` | `unknown`    |

package/api/@xmachines/play-atom/variables/createAsyncAtom.md

@@ -7,7 +7,7 @@ const createAsyncAtom: <T>(getValue, options?) => ReadonlyAtom<AsyncAtomState<T>
 	createEngineAsyncAtom;
 ```
 
-Defined in: [create-atom.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L64)
+Defined in: [create-atom.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/create-atom.ts#L64)
 
 Builds a read-only atom that holds the state of a promise
 
@@ -19,9 +19,9 @@ signal takes no parameter.
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `T`            |
+| Type Parameter                          |
+| --------------------------------------- |
+| <a id="type-parameter-__typet"></a> `T` |
 
 ## Parameters
 

package/api/@xmachines/play-atom/variables/createAtom.md

@@ -6,7 +6,7 @@
 const createAtom: CreateAtom = createEngineAtom;
 ```
 
-Defined in: [create-atom.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-atom.ts#L47)
+Defined in: [create-atom.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/create-atom.ts#L47)
 
 Builds a writable atom from a value, and a computed atom from a function
 

package/api/@xmachines/play-atom/variables/createWritableAtom.md

@@ -6,7 +6,7 @@
 const createWritableAtom: <T>(initialValue, options?) => Atom<T> = createAtom;
 ```
 
-Defined in: [create-writable-atom.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-atom/src/create-writable-atom.ts#L50)
+Defined in: [create-writable-atom.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-atom/src/create-writable-atom.ts#L50)
 
 Builds a WRITABLE atom, and never a computed one.
 
@@ -37,9 +37,9 @@ the first `set` call throws. Hold a function in a wrapper — `createWritableAto
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `T`            |
+| Type Parameter                          |
+| --------------------------------------- |
+| <a id="type-parameter-__typet"></a> `T` |
 
 ## Parameters
 

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.1.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.1.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}`,
@@ -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,26 +295,53 @@ 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:
+
+- **`"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).
 
-- **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.
+`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
 
@@ -303,6 +359,11 @@ a framework is not an option that a caller turns off. play-dom follows the same
 
 ```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) => {
@@ -316,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, and a bad initial view does not make `connect()` throw.
+`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.
 
@@ -331,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")!,
@@ -345,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;
 	}
 };
@@ -375,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.
 
@@ -439,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)
@@ -458,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