@xmachines/play-dom 2.0.0-alpha.1 → 2.1.0

package/README.md

@@ -1,10 +1,8 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-dom
 
 Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
 
-Part of the [XMachines Play monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -15,14 +13,16 @@ pnpm add @xmachines/play-dom
 **Peer dependencies:**
 
 ```bash
-pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-xstate
+pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate
 ```
 
 ## Quick Start
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
+import { definePlayer } from "@xmachines/play-xstate";
 import { defineCatalog } from "@xmachines/json-render-core";
+import { createMachine } from "xstate";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
 
@@ -57,10 +57,36 @@ const Login: ComponentFn<typeof catalog, "Login"> = ({ props, on }) => {
 // 3. Build the factory once (module scope)
 const mount = createRenderer(catalog, { Home, Login });
 
-// 4. Mount when actor and container are ready
+// 4. Create and start an actor — states carry meta.view specs naming catalog components
+const machine = createMachine({
+	initial: "home",
+	states: {
+		home: {
+			on: { "goto.login": "login" },
+			meta: {
+				view: {
+					root: "root",
+					elements: { root: { type: "Home", props: { title: "Home" }, children: [] } },
+				},
+			},
+		},
+		login: {
+			meta: {
+				view: {
+					root: "root",
+					elements: { root: { type: "Login", props: { title: "Login" }, children: [] } },
+				},
+			},
+		},
+	},
+});
+const actor = definePlayer({ machine })();
+actor.start();
+
+// 5. Mount when actor and container are ready
 const disconnect = mount(actor, document.getElementById("app")!);
 
-// 5. Cleanup on teardown
+// 6. Cleanup on teardown
 disconnect();
 ```
 
@@ -68,7 +94,7 @@ disconnect();
 
 ### `createRenderer` — one-call factory (recommended)
 
-`createRenderer` is the simplest integration path. Call it once at module scope with your catalog and component map, then call the returned `mount` function for each actor/container pair.
+`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
 import { createRenderer, schema } from "@xmachines/play-dom";
@@ -78,16 +104,17 @@ const catalog = defineCatalog(schema, {/* ... */});
 
 const mount = createRenderer(catalog, { MyComponent });
 
+// actor from the Quick Start
 const disconnect = mount(actor, document.getElementById("app")!);
 // Returns a cleanup function — call it to stop rendering and clear the container.
 disconnect();
 ```
 
-### `createPlayUI` — batteries-included factory with full options
+### `createPlayUI` — the complete factory with every option
 
-Use `createPlayUI` when you need render error handling, a fallback element, navigation integration, computed functions, or custom validation — or when you need to reference `registryResult` programmatically (e.g. for `executeAction`).
+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`.
 
-Factory-level options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, `fallback`) are closed over at creation time and applied on every `mount()` call. Per-mount options (`store`, `loading`) are passed to `mount()` itself.
+The factory holds the factory options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and it applies them on every `mount()` call. Give the mount options (`store` and `loading`) to `mount()` itself.
 
 ```typescript
 import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
@@ -95,6 +122,7 @@ import { defineCatalog } from "@xmachines/json-render-core";
 
 const catalog = defineCatalog(schema, {/* ... */});
 
+// Home, Login, actor from the Quick Start
 const registryResult = defineRegistry(catalog, {
 	components: { Home, Login },
 	actions: {
@@ -120,13 +148,15 @@ disconnect();
 
 ### `PlayRenderer` — class-based lifecycle control
 
-Use `PlayRenderer` directly when you need explicit `connect()` / `disconnect()` lifecycle control, or when integrating into a system that manages the renderer's lifetime externally.
+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";
 
+// catalog, actor from the Quick Start; components/actions as in the createPlayUI example
 const registryResult = defineRegistry(catalog, { components, actions });
 
+// container: your mount element, e.g. document.getElementById("app")!
 const renderer = new PlayRenderer(container, actor, registryResult.registry, { registryResult });
 
 renderer.connect();
@@ -134,15 +164,16 @@ renderer.connect();
 renderer.disconnect();
 ```
 
-**Controlled store mode** — supply an external `StateStore` so the renderer shares state with other parts of your app:
+**Controlled store mode.** Give the renderer an external `StateStore`. The renderer then shares the state with the other parts of your application:
 
 ```typescript
 import { createAtom } from "@xstate/store";
 import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
 
-const atom = createAtom({ username: "" });
+const atom = createAtom<Record<string, unknown>>({ username: "" });
 const store = xstateStoreStateStore({ atom });
 
+// container, actor, registryResult from the previous example
 const renderer = new PlayRenderer(container, actor, registryResult.registry, {
 	registryResult,
 	store,
@@ -152,11 +183,11 @@ renderer.connect();
 
 ## Provider Options
 
-All entry points (`createPlayUI`, `PlayRenderer`) accept the same set of UI-provider options via `UIProviderOptions`. These are forwarded into `DomRenderContext` on every render pass, making them available to component implementations via `ctx.ctx.*`.
+Every entry point (`createPlayUI` and `PlayRenderer`) accepts the same UI-provider options, through `UIProviderOptions`. Each render pass puts the options into `DomRenderContext`. A component implementation therefore reads them at `ctx.ctx.*`.
 
 ### `functions` — named compute functions for `$computed` prop expressions
 
-Enables `{ "$computed": "name", "args": {...} }` dynamic prop values in specs. Each function receives the resolved `args` object and returns the computed value.
+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
 const mount = createPlayUI(registryResult, {
@@ -167,13 +198,13 @@ const mount = createPlayUI(registryResult, {
 });
 ```
 
-Without `functions`, any `$computed` expression silently resolves to `undefined` (no throw, backward-compatible).
+Without `functions`, every `$computed` expression resolves to `undefined`. Nothing throws, and the old behavior stays.
 
 ### `validationFunctions` — custom field validation
 
-Provides named validation functions for inline field validation within components. Functions receive `(value, args?)` and return `true` (valid) or `false` (invalid).
+This option gives the named check functions for a field check inside a component. Each function receives `(value, args?)`. It returns `true` for a valid value, or `false` for an invalid value.
 
-Unlike the framework renderers, the DOM renderer has no automatic `ValidationProvider` tree. Components must invoke validation explicitly using `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`, passing `ctx.ctx.validationFunctions` as `customFunctions`.
+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";
@@ -185,19 +216,21 @@ const mount = createPlayUI(registryResult, {
 	},
 });
 
-// Inside a ComponentFn:
-const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => {
+// Inside a ComponentFn (catalog from the Quick Start):
+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 },
 	);
 	// result.valid, result.message
+	return null;
 };
 ```
 
 ### `navigate` — programmatic navigation from action bindings
 
-A callback invoked when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Integrate with any router:
+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
 // React Router / TanStack Router / any push-based router:
@@ -219,17 +252,17 @@ With a spec binding:
 }
 ```
 
-When `submitForm` completes successfully, `navigate("/dashboard")` is called automatically.
+`submitForm` completes without an error, and the renderer then calls `navigate("/dashboard")`.
 
-The function is also readable by component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding.
+A component implementation can also read the function at `ctx.ctx.navigate`. Use this when a navigation must start outside an action binding.
 
 ### `onRenderError` — unified error handler
 
-Receives `(error, name)` for three distinct error classes:
+The handler receives `(error, name)` for three different classes of error:
 
-- **Component render errors** — when a `ComponentFn` throws synchronously during `renderSpec`. `name` is the catalog component name (e.g. `"Home"`).
-- **Action handler rejections (emit path)** — when an `ActionFn` throws or returns a rejected promise during `emit()`. `name` is the catalog action name (e.g. `"submitForm"`).
-- **Action handler rejections (watch path)** — when an `ActionFn` rejects during a `watch` binding callback. `name` is the catalog action name.
+- **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.
 
 ```typescript
 const mount = createPlayUI(registryResult, {
@@ -240,19 +273,20 @@ const mount = createPlayUI(registryResult, {
 });
 ```
 
-The argument order matches the upstream `RenderErrorHandler` type from `@xmachines/json-render-core`: **error first, name second**. This is consistent with the framework renderers (`@xmachines/json-render-solid`, `@xmachines/json-render-react`).
+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.
 
-Without `onRenderError`, all three error types are logged via `console.error` and swallowed. No exception propagates, and no unhandled promise rejection is created.
+Without `onRenderError`, the renderer writes all three types of error to `console.error`, then stops them. No exception goes to the caller, and no promise rejection stays unhandled.
 
-The handler is also available to component implementations via `ctx.ctx.onRenderError`, enabling components to route their 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:
 
 ```typescript
-const MyComponent: ComponentFn<typeof catalog, "MyComponent"> = ({ ctx }) => {
+// catalog from the Quick Start; doSomethingRisky: 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, "MyComponent");
+		ctx.ctx.onRenderError?.(err, "Home");
 		return null;
 	}
 };
@@ -262,42 +296,42 @@ const MyComponent: ComponentFn<typeof catalog, "MyComponent"> = ({ ctx }) => {
 
 ### XMachines Layer
 
-| Export                                   | Kind     | Description                                                                 |
-| ---------------------------------------- | -------- | --------------------------------------------------------------------------- |
-| `createRenderer(catalog, components)`    | function | One-call factory — returns `mount(actor, container, options?) → disconnect` |
-| `createPlayUI(registryResult, options?)` | function | Batteries-included factory — returns `MountFn`                              |
-| `PlayRenderer`                           | class    | Class-based renderer with `connect()` / `disconnect()` lifecycle            |
-| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                     |
-| `renderSpec(...)`                        | function | Pure Spec → DOM renderer (low-level)                                        |
-| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()`         |
+| Export                                   | Kind     | Description                                                                       |
+| ---------------------------------------- | -------- | --------------------------------------------------------------------------------- |
+| `createRenderer(catalog, components)`    | function | The one-call factory. It returns `mount(actor, container, options?) → disconnect` |
+| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `MountFn`                                      |
+| `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle               |
+| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                           |
+| `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                                            |
+| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()`               |
 
 ### Key Types
 
-| Type                     | Description                                                                                |
-| ------------------------ | ------------------------------------------------------------------------------------------ |
-| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                   |
-| `ComponentContext<C, K>` | Context passed to each component: `props`, `children`, `emit`, `on`, `bindings`, `ctx`     |
-| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                       |
-| `EventHandle`            | Handle returned by `on(eventName)` — has `emit()`, `shouldPreventDefault`, `bound`         |
-| `SetState`               | State updater: `(prev => next) => void`                                                    |
-| `DefineRegistryResult`   | Result from `defineRegistry` — has `registry`, `handlers`, `executeAction`                 |
-| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`                                   |
-| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback`                  |
-| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                        |
-| `MountFn`                | The mount function returned by `createPlayUI`: `(actor, container, options?) → disconnect` |
-| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`            |
-| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                            |
-| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                  |
-| `DomSchema`              | Type of the `schema` export                                                                |
-| `ComputedFunction`       | Type for named compute functions used with the `functions` option                          |
-
-## Rendering Behaviour
-
-- **Initial render is synchronous** — the container is populated before `connect()` returns.
-- **Signal-driven re-renders are microtask-deferred** — `watchSignal` schedules updates on the next microtask queue tick.
-- **Null view** clears the container. A `fallback` element can be shown on initial mount when the view is `null`; it is **not** re-appended if the view later transitions back to `null` after a non-null view.
-- **Double `connect()` is safe** — calling `connect()` on an already-connected renderer auto-disconnects first.
-- **`disconnect()` clears the container** and unsubscribes all signal and store watchers.
+| Type                     | Description                                                                                   |
+| ------------------------ | --------------------------------------------------------------------------------------------- |
+| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                      |
+| `ComponentContext<C, K>` | The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`       |
+| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                          |
+| `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound` |
+| `SetState`               | State updater: `(prev => next) => void`                                                       |
+| `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`            |
+| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`                                      |
+| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback`                     |
+| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                           |
+| `MountFn`                | The mount function that `createPlayUI` returns: `(actor, container, options?) → disconnect`   |
+| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`               |
+| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                               |
+| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                     |
+| `DomSchema`              | Type of the `schema` export                                                                   |
+| `ComputedFunction`       | The type of a named compute function for the `functions` option                               |
+
+## Rendering Behavior
+
+- **The first render is synchronous** — the renderer fills the container before `connect()` returns.
+- **A signal-driven render waits for a microtask** — `watchSignal` puts each update on the next tick of the microtask queue.
+- **A null view** clears the container. The renderer can show a `fallback` element on the first mount, when the view is `null`. It does **not** add that element again when the view returns to `null` after a view that was not null.
+- **A second `connect()` is safe** — a `connect()` call on a connected renderer disconnects it first.
+- **`disconnect()` clears the container** and cancels every signal watcher and store watcher.
 
 ## Testing
 
@@ -309,4 +343,4 @@ pnpm test
 pnpm run test:coverage
 ```
 
-Tests live in `test/` and use [Vitest](https://vitest.dev/) with a jsdom environment. Coverage thresholds: 80% lines, functions, branches, and statements.
+The tests are in `test/`. They use [Vitest](https://vitest.dev/) in a jsdom environment. The coverage thresholds are 80% for lines, functions, branches, and statements.

package/dist/PlayRenderer.d.ts

@@ -1,38 +1,41 @@
 /**
- * PlayRenderer.ts — XMachines wrapper around @xmachines/json-render-dom.
+ * PlayRenderer.ts — the XMachines wrapper of @xmachines/json-render-dom.
  *
- * Bridges actor.currentView (TC39 Signal) to the inner DOM renderer using watchSignal.
- * Exposes connect() / disconnect() methods following the same pattern as
- * play-react, play-vue, and play-solid PlayRenderer classes.
+ * It connects actor.currentView, a TC39 Signal, to the DOM renderer below it, with
+ * watchSignal. 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.
  *
- * State store: uses external `store` option if provided (controlled mode); otherwise
- * creates a fresh @xstate/store atom per view transition seeded from spec.state.
+ * The state store: the renderer uses the external `store` option when the caller
+ * gives one, and this is the controlled mode. Without that option, it makes a new
+ * @xstate/store atom for each view transition, with the values of spec.state.
  */
 import type { AbstractActor, Viewable } from "@xmachines/play-actor";
 import type { AnyActorLogic } from "xstate";
 import type { DomRegistry } from "@xmachines/json-render-dom";
 import type { PlayDomOptions } from "./types.js";
 /**
- * PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
+ * PlayRenderer connects the `currentView` signal of an actor to the DOM renderer.
  *
- * Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
- * functions into `container` on every view transition. Cleared on `disconnect()`.
+ * It watches `actor.currentView` through the TC39 Signals. It renders each
+ * `DomComponentRenderer` function into `container` on every view transition.
+ * `disconnect()` clears the container.
  *
- * Options from `PlayDomOptions` (which extends `UIProviderOptions`) are all forwarded
- * into `DomRenderContext` on every render pass:
- * - `functions` — named compute functions for `{ $computed: "name" }` prop expressions
- * - `directives` — custom `$`-prefixed dynamic values (from `defineDirective`), resolved during prop resolution
- * - `validationFunctions` — custom validation functions, available at `ctx.ctx.validationFunctions`
- * - `navigate` — navigation callback, invoked on `onSuccess: { navigate: "..." }` action bindings
- * - `onRenderError` — called with `(error, name)` for component render errors and action handler rejections
+ * Every option of `PlayDomOptions`, which extends `UIProviderOptions`, goes into
+ * `DomRenderContext` on each render pass:
+ * - `functions` — the named compute functions of a `{ $computed: "name" }` prop expression
+ * - `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
  *
- * **Preferred usage — via `registryResult`:**
+ * **The preferred use, with `registryResult`:**
  * ```typescript
  * import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
  *
  * const registryResult = defineRegistry(catalog, { components, actions });
  * const renderer = new PlayRenderer(container, actor, registryResult.registry, {
- *   registryResult, // wires setState/getState from xstate store automatically
+ *   registryResult, // it connects setState and getState of the xstate store for you
  *   navigate: (path) => myRouter.push(path),
  *   functions: { fullName: (args) => `${args.first} ${args.last}` },
  * });
@@ -41,7 +44,7 @@ import type { PlayDomOptions } from "./types.js";
  * renderer.disconnect();
  * ```
  *
- * **Controlled store mode** — bring your own `StateStore`:
+ * **The controlled store mode** — you give your own `StateStore`:
  * ```typescript
  * import { createAtom } from "@xstate/store";
  * import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
@@ -52,8 +55,9 @@ import type { PlayDomOptions } from "./types.js";
  * renderer.connect();
  * ```
  *
- * Double `connect()` is safe — calling `connect()` while already connected
- * automatically disconnects first, preventing double-render subscriptions.
+ * A second `connect()` is safe. A `connect()` call on a connected renderer
+ * disconnects it first. Therefore the renderer holds no second render
+ * subscription.
  */
 export declare class PlayRenderer {
     private readonly container;
@@ -63,59 +67,96 @@ export declare class PlayRenderer {
     private unwatch;
     private storeUnsubscribe;
     /**
-     * Live watch-subscription cleanups. A `Set` (not an array) so that each
-     * registered cleanup can delete ITSELF on invocation: the incremental
-     * renderer releases a watcher when its element unmounts, and the registered
-     * wrapper is what it invokes — so the Set shrinks in lock-step with live
-     * subscriptions instead of accumulating one spent closure per historical
-     * mount over a long-lived view.
+     * The cleanup functions of the live watch subscriptions. This field is a `Set`,
+     * and not an array, so that each registered cleanup function can delete ITSELF on
+     * its call: the incremental renderer releases a watcher when its element unmounts,
+     * and it calls the registered wrapper. The Set therefore shrinks with the live
+     * subscriptions. It does not collect one spent closure for each historical mount of
+     * a view with a long life.
      */
     private watchCleanups;
     /**
-     * Set to `false` in `disconnect()` before calling `storeUnsub()`.
-     * The `rerender` closure checks this flag at entry so that any synchronous
-     * callback fired by the `StateStore` implementation within its own
-     * `unsubscribe()` call (an edge-case but valid contract) does not mutate a
-     * detached DOM tree.
+     * 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.
+     */
+    private lastViewKey;
+    private currentStore;
+    /**
+     * The shared coordinator of the store lifecycle, from @xmachines/play-actor. 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.
+     */
+    private readonly storeLifecycle;
+    /**
+     * `disconnect()` sets this field to `false` before it calls `storeUnsub()`.
+     * The `rerender` closure reads the flag at its start. Therefore a synchronous
+     * callback from the `StateStore` implementation inside its own `unsubscribe()`
+     * call, which is rare but correct, changes no detached DOM tree.
      */
     private alive;
     /**
-     * @param container - `HTMLElement` to render into. Cleared and repopulated on every view transition.
-     * @param actor     - Actor providing the `currentView` signal (must implement `Viewable`).
-     * @param registry  - Component renderer map — typically `registryResult.registry` from `defineRegistry`.
-     * @param options   - Configuration (see {@link PlayDomOptions}):
-     *   - `registryResult`      — auto-wires `setState`/`state` from the xstate store.
-     *   - `store`               — external `StateStore` (controlled mode; overrides `spec.state` seeding).
-     *   - `loading`             — streaming mode flag; suppresses missing-child warnings.
-     *   - `functions`           — named compute functions for `$computed` prop expressions.
-     *   - `directives`          — custom `$`-prefixed dynamic values resolved during prop resolution.
-     *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
-     *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
-     *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections; suppresses `console.error` fallback.
+     * @param container - The `HTMLElement` to render into. Each view transition clears it and fills it again.
+     * @param actor     - The actor with the `currentView` signal. It must implement `Viewable`.
+     * @param registry  - The map of the component renderers, usually `registryResult.registry` from `defineRegistry`.
+     * @param options   - The configuration. See {@link PlayDomOptions}:
+     *   - `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.
      */
     constructor(container: HTMLElement, actor: AbstractActor<AnyActorLogic> & Viewable, registry: DomRegistry, options?: PlayDomOptions);
     /**
-     * Start watching actor.currentView and render to container.
-     * Renders the initial view synchronously, then subscribes to signal changes.
+     * Starts the watch of actor.currentView, and renders into the container.
+     * It renders the first view synchronously, then it subscribes to the signal changes.
      *
-     * Calling `connect()` on an already-connected renderer (where a previous
-     * `connect()` was never followed by `disconnect()`) would silently install a
-     * second `watchSignal` subscription, causing double-renders on every view
-     * change. Guard against this by auto-disconnecting first.
+     * A `connect()` call on a connected renderer, where a `disconnect()` call did not
+     * follow the previous `connect()`, installs a second `watchSignal` subscription.
+     * Each view change then renders two times. Therefore this method disconnects the
+     * renderer first.
      */
     connect(): void;
     /**
-     * Stop watching and clear the container.
+     * Stops the watch and clears the container.
      */
     disconnect(): void;
     /**
-     * Number of live watch-subscription cleanups currently retained.
+     * The number of live watch-subscription cleanup functions now.
      *
-     * @internal Test-only accessor for asserting that the watch-cleanup
-     * collection tracks live registrations (no per-mount leak). Not part of the
-     * public API and may change without notice.
+     * @internal This accessor is for a test only. A test asserts with it that the
+     * collection of the watch cleanups holds the live registrations, and that no mount
+     * leaks. It is not part of the public API, and it can change without a notice.
      */
     get watchCleanupCount(): number;
     private render;
+    /**
+     * A rebuild that fails must not leave the guard of the fast path armed on a dead
+     * tree, because the container is empty already. Therefore this code resets the view
+     * identity. The next emission, also one with the same viewKey, then makes a
+     * complete render again. It does not patch a store that nothing shows.
+     */
+    private resetFailedRebuild;
+    /**
+     * 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.
+     */
+    private renderView;
 }
 //# sourceMappingURL=PlayRenderer.d.ts.map

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,YAAY;IAoCvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtCzB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAyB;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;;;;;OAaG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,UAAU,IAAI,IAAI;IAmBlB;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,OAAO,CAAC,MAAM;CAuId"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,YAAY;IA2DvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA7DzB,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;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAE7B;IACF;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;;;;;OAaG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,UAAU,IAAI,IAAI;IAyBlB;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,OAAO,CAAC,MAAM;IAqEd;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CA+GlB"}