@xmachines/play-dom 6.0.0 → 7.0.0

package/README.md

@@ -2,7 +2,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
 
@@ -13,9 +13,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
@@ -104,7 +106,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";
 
@@ -122,9 +124,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";
 
@@ -159,12 +161,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();
@@ -172,16 +176,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,
@@ -198,6 +207,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}`,
@@ -206,7 +219,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
 
@@ -215,7 +228,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: {
@@ -224,12 +242,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;
@@ -241,7 +264,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),
 });
@@ -264,48 +293,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) => {
@@ -319,13 +375,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.
 
@@ -334,6 +390,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")!,
@@ -348,16 +410,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;
 	}
 };
@@ -378,27 +450,29 @@ 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.

package/dist/PlayRenderer.d.ts

@@ -1,8 +1,8 @@
 /**
  * PlayRenderer.ts — the XMachines wrapper of @xmachines/json-render-dom.
  *
- * It connects actor.currentView, an atom, to the DOM renderer below it, with
- * watchAtom. It gives you the connect() method and the disconnect() method, in
+ * It connects actor.currentView, an atom, to the DOM renderer below it, through the
+ * view session of @xmachines/play-view. It gives you the connect() method and the disconnect() method, in
  * the same pattern as the PlayRenderer class of play-react, of play-vue, and of
  * play-solid.
  *
@@ -26,7 +26,7 @@ import type { PlayDomOptions } from "./types.js";
  * - `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`:**
  * ```typescript
@@ -84,29 +84,37 @@ export declare class PlayRenderer {
      */
     private watchCleanups;
     /**
-     * The viewKey of the view on the screen now, and the store behind it, without the
-     * guard. An emission with the same key means that only the /context projection
-     * moved: the fast path for a slice in render() refreshes the store in place, and it
-     * does not remove the tree. The ephemeral view state, such as a draft or a toggle,
-     * therefore stays. A null emission, from a state with no meta.view, is a GAP, and
-     * not a new view: the DOM goes away, but the identity and the store stay. A return
-     * to the same view therefore builds again around the ephemeral state that survived,
-     * in the same way as the framework providers. `disconnect()` resets both fields,
-     * because a store that stays alive must not outlive the connection.
+     * The generation of the store behind the tree on the screen, from the lifecycle. A
+     * resolution with the same generation keeps the store: only the /context projection
+     * moved, or a composed view changed its page, so the renderer keeps the tree and the
+     * ephemeral view state, such as a draft or a toggle. A new generation is a new store,
+     * and the renderer builds the tree again. A null emission, from a state with no
+     * meta.view, is a GAP, and not a new view: the DOM goes away, but the lifecycle keeps
+     * the store. A return to the same view therefore builds again around the ephemeral
+     * state that survived, in the same way as the framework providers.
      */
-    private lastViewKey;
-    private currentStore;
+    private treeGeneration;
+    /**
+     * The incremental renderer of the live tree, and the `root` and `elements` of the
+     * spec that it renders. An emission with the same viewKey and the same two
+     * references moved the /context projection alone. An emission with the same
+     * viewKey and a new `elements` object is a new spec of the same view — a composed
+     * view whose page changed, or a streamed chunk — and the renderer takes it in place
+     * through `setSpec`.
+     */
+    private incremental;
+    private lastRoot;
+    private lastElements;
     /** The fallback element, built at the first moment that the renderer shows it. */
     private fallbackElement;
     /**
-     * The shared coordinator of the store lifecycle, from @xmachines/play-view. It
-     * seeds the store again on a change of the viewKey, it refreshes /context in place
-     * in every other case, and it guards the identity cache. The two fields above,
-     * lastViewKey and currentStore, stay as the DOM-side record for the fast path of a
-     * slice. That path is about the live TREE, which is the spec and the subscription,
-     * and not about the store.
+     * The view session of the connection, from @xmachines/play-view. It resolves the store
+     * of each view by the rules of the lifecycle — it seeds the store again on a change of
+     * the viewKey, and it refreshes /context in place in every other case — and it hands
+     * this renderer one snapshot for each attempt. Its generation decides whether the live
+     * tree stays. `connect()` makes one, and `disconnect()` drops it with its store.
      */
-    private readonly storeLifecycle;
+    private session;
     /**
      * `disconnect()` sets this field to `false` before it calls `storeUnsub()`.
      * The `rerender` closure reads the flag at its start. Therefore a synchronous
@@ -114,6 +122,17 @@ export declare class PlayRenderer {
      * call, which is rare but correct, changes no detached DOM tree.
      */
     private alive;
+    /**
+     * The depth of the synchronous calls into the inner renderer: `render()`, `setSpec()`
+     * and `update()`. A failure of the root that the inner renderer reports inside such a
+     * call waits for the end of the call. See {@link PlayRenderer.failRoot}.
+     */
+    private innerDepth;
+    /**
+     * The failure of the root that the inner renderer reported, until the renderer
+     * contains it, and the inner renderer that reported it.
+     */
+    private rootFailure;
     /**
      * The report guard, from @xmachines/play-view.
      *
@@ -145,8 +164,8 @@ export declare class PlayRenderer {
      *   - `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.
+     *   - `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.
      */
     constructor(container: HTMLElement, actor: ViewActor, registry: DomRegistry, options?: PlayDomOptions);
@@ -155,7 +174,7 @@ export declare class PlayRenderer {
      * 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.
      */
@@ -164,6 +183,20 @@ export declare class PlayRenderer {
      * Stops the watch and clears the container.
      */
     disconnect(): void;
+    /**
+     * Releases the store subscription and the watch subscriptions of the tree.
+     *
+     * It captures both and clears both BEFORE a release. Some store implementations fire a
+     * synchronous callback during their unsubscribe(). Without this order, that callback
+     * sees a live storeUnsubscribe, and it enters the rerender path again with an old view
+     * and an old store, or it overwrites watchCleanups before the loop below reaches it.
+     *
+     * See reportReleaseFailure: a throw of one release must skip none of the work below it.
+     * This is code of a caller, and it also runs on the path of a view that WORKS.
+     */
+    private releaseTree;
+    /** Forgets the tree on the screen, so that the next emission builds it again. */
+    private forgetTree;
     /**
      * The number of live watch-subscription cleanup functions now.
      *
@@ -172,19 +205,90 @@ export declare class PlayRenderer {
      * leaks. It is not part of the public API, and it can change without a notice.
      */
     get watchCleanupCount(): number;
+    /**
+     * Brings the screen in line with one snapshot of the view session.
+     *
+     * The session resolved the store already: it refreshed /context in place, or it seeded
+     * a new store, or it recorded the failure of `spec.state`. This method decides the
+     * tree alone.
+     */
     private render;
+    /**
+     * Takes the tree of the previous view off the screen, before a rebuild.
+     *
+     * The watch subscriptions of the previous view must go too. Without this step, they
+     * stay active between a view transition and the first store update of the new view.
+     * They then hold a reference to a DOM element that is gone, and the garbage collector
+     * cannot take it.
+     */
+    private clearTree;
     /**
      * The end of a render that failed, in ONE place.
      *
      * Three paths render — the fast path of a slice, the complete rebuild, and the write
-     * of the store — and each one ends here. The ORDER is load-bearing: the reset takes
-     * the registrations of the dead tree down BEFORE the report, so a handler of the host
-     * that renders again meets a renderer that holds nothing of the failed attempt. A
-     * second copy of the pair is a second chance to put the two in the other order.
+     * of the store — and each one ends here: through a throw, or through a failure of the
+     * root that the inner renderer reports (see {@link PlayRenderer.failRoot}). The ORDER
+     * is load-bearing: the reset takes the registrations of the dead tree down BEFORE the
+     * report, so a handler of the host that renders again meets a renderer that holds
+     * nothing of the failed attempt. A second copy of the pair is a second chance to put
+     * the two in the other order.
      *
      * @param error - The failure that the renderer contains.
      */
     private failView;
+    /**
+     * Gives a failure that the inner renderer reports to the handler of the host, and
+     * contains a failure of the ROOT as a failure of the view.
+     *
+     * The inner renderer reports each failure one time, with `(error, name, info)`. This
+     * method gives each one to `forwardRenderError` of @xmachines/play-view, which holds
+     * the rule of the five renderers: the `onRenderError` of the host, or the handler of the
+     * registry, or the one `[json-render]` console line.
+     *
+     * A failure of the root — its component, a prop, or its `visible` condition — leaves
+     * no view on the screen. The inner renderer throws it to no caller, so the renderer
+     * contains it here, as it contains a complete rebuild that throws: it shows the
+     * fallback, and it reports the failure to `onError` one time. A handler of the host
+     * also gets it, with `info.kind` `"root"`. Without such a handler, the method writes
+     * no `[json-render]` line for it: the containment reports it to `onError`, or to its
+     * own console line, and a second line would report one failure two times.
+     *
+     * @param owner - The inner renderer that this handler belongs to, or `null` before it exists.
+     */
+    private reportInner;
+    /**
+     * Contains a failure of the root that the inner renderer reported.
+     *
+     * The report comes in the middle of the work of the inner renderer, which writes the
+     * container after it. The containment therefore waits for the end of that work. Inside
+     * a synchronous call, {@link PlayRenderer.callInner} contains the failure when the call
+     * returns. At the commit point of a store write, which no call of this class holds, a
+     * microtask contains it.
+     *
+     * @param owner - The inner renderer that reported the failure.
+     * @param error - The failure of the root.
+     */
+    private failRoot;
+    /**
+     * Hands the failure of the root that waits to the session, when it belongs to the
+     * live tree.
+     *
+     * The four framework providers take the same path: `failView` of the session records
+     * the failure in a new snapshot, and it gives the next attempt a new generation. The
+     * session then notifies this renderer, and `render()` contains the failed snapshot
+     * with {@link PlayRenderer.failView}: it clears the tree, shows the fallback, and
+     * reports to `onError` one time. The session has no `onFailure` here, so it reports
+     * nothing of its own.
+     */
+    private settleRoot;
+    /**
+     * Runs one synchronous call into the inner renderer, and then contains a failure of the
+     * root that the call reported.
+     *
+     * @param owner - The inner renderer of the call.
+     * @param call - The call: `render()`, `setSpec()` or `update()`.
+     */
+    private callInner;
     /**
      * Clears the screen of the failed view, shows the fallback, and reports the failure.
      *
@@ -249,10 +353,12 @@ export declare class PlayRenderer {
     /**
      * The tail of a complete rebuild, which can throw. See the catch block of render().
      *
-     * @param guardedStore - Everything that the spec can write through, which includes
-     *   $bindState, setState, and a chained set, receives the GUARDED store: /context is
-     *   read-only to the spec, because the machine context changes through an event
-     *   only.
+     * @param view - The view to render.
+     * @param guardedStore - The store of the view, from the session. Everything that the
+     *   spec can write through, which includes $bindState, setState, and a chained set,
+     *   receives the GUARDED store: /context is read-only to the spec, because the machine
+     *   context changes through an event only.
+     * @param generation - The generation of that store, which the tree records.
      */
     private renderView;
 }

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,OAAO,KAAK,EAAmC,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKvF,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAsDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,YAAY;IA+FvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjGzB;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAyB;IAC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,YAAY,CAA2B;IAC/C,kFAAkF;IAClF,OAAO,CAAC,eAAe,CAA4B;IACnD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAE7B;IACF;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;OASG;IAGH,OAAO,CAAC,KAAK,CAAkD;IAE/D;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAwC;IAErD;;;;;;;;;;;;;;;OAeG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAyCf;;OAEG;IACH,UAAU,IAAI,IAAI;IA4BlB;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,OAAO,CAAC,MAAM;IAmGd;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,OAAO;IAiBf;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAuB1B;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CA6HlB"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EAEX,SAAS,EAGT,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAsDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,YAAY;IAkHvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IApHzB;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAyB;IAC9C;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc,CAAiC;IACvD;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,YAAY,CAA+C;IACnE,kFAAkF;IAClF,OAAO,CAAC,eAAe,CAA4B;IACnD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,CAA4B;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAK;IAEvB;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAkE;IAErF;;;;;;;;;OASG;IAGH,OAAO,CAAC,KAAK,CAAkD;IAE/D;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAwC;IAErD;;;;;;;;;;;;;;;OAeG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IA2Bf;;OAEG;IACH,UAAU,IAAI,IAAI;IAgBlB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW;IAiBnB,iFAAiF;IACjF,OAAO,CAAC,UAAU;IAOlB;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAiEd;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAUjB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ;IAOhB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IAOlB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAUjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,OAAO;IAiBf;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU;CAuHlB"}