@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,30 +2,31 @@
 
 # Class: PlayRenderer
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L68)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/PlayRenderer.ts#L72)
 
-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:
+Every option of `PlayDomOptions`, which extends `UIProviderOptions`, goes into
+`DomRenderContext` on each 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
+- `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}` },
 });
@@ -34,7 +35,7 @@ renderer.connect();
 renderer.disconnect();
 ```
 
-**Controlled store mode** — bring your own `StateStore`:
+**The controlled store mode** — you give your own `StateStore`:
 
 ```typescript
 import { createAtom } from "@xstate/store";
@@ -46,8 +47,9 @@ const renderer = new PlayRenderer(container, actor, registry, { registryResult,
 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.
 
 ## Constructors
 
@@ -61,16 +63,16 @@ new PlayRenderer(
    options?): PlayRenderer;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L126)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/PlayRenderer.ts#L130)
 
 #### Parameters
 
-| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | `HTMLElement` to render into. Cleared and repopulated on every view transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor providing the `currentView` signal (must implement `Viewable`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Component renderer map — typically `registryResult.registry` from `defineRegistry`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)                                                                                                                                                                                                              | Configuration (see [PlayDomOptions](../interfaces/PlayDomOptions.md)): - `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. |
+| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | The `HTMLElement` to render into. Each view transition clears it and fills it again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | The actor with the `currentView` signal. It must implement `Viewable`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | The map of the component renderers, usually `registryResult.registry` from `defineRegistry`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)                                                                                                                                                                                                              | The configuration. See [PlayDomOptions](../interfaces/PlayDomOptions.md): - `registryResult` — it connects `setState` and `state` of the xstate store for you. - `store` — an external `StateStore`, which is the controlled mode. It replaces the values of `spec.state`. - `loading` — the flag of the streaming mode. It stops each warning about an absent child. - `functions` — the named compute functions of a `$computed` prop expression. - `directives` — your own dynamic values with a `$` prefix. The renderer resolves them with the props. - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`. - `navigate` — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`. - `onRenderError` — the `(error, name)` handler of a component render error and of an action handler rejection. It stops the `console.error` fallback. |
 
 #### Returns
 
@@ -84,15 +86,15 @@ Defined in: [packages/play-dom/src/PlayRenderer.ts:126](https://gitlab.com/xmach
 connect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L142)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/PlayRenderer.ts#L146)
 
-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.
 
 #### Returns
 
@@ -106,9 +108,9 @@ change. Guard against this by auto-disconnecting first.
 disconnect(): void;
 ```
 
-Defined in: [packages/play-dom/src/PlayRenderer.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/PlayRenderer.ts#L151)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/PlayRenderer.ts#L155)
 
-Stop watching and clear the container.
+Stops the watch and clears the container.
 
 #### Returns
 

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

@@ -6,23 +6,23 @@
 function createPlayUI(registryResult, options?): MountFn;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-play-ui.ts#L93)
+Defined in: [packages/play-dom/src/create-play-ui.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L95)
 
-Create a batteries-included DOM renderer mount function.
+Creates the mount function of the complete DOM renderer.
 
-The caller is responsible for producing `registryResult` via `defineRegistry`.
-`createPlayUI` closes over it and returns a `MountFn` that can be invoked
-once per actor/container pair.
+The caller makes `registryResult` with `defineRegistry`. `createPlayUI` holds it,
+and it returns a `MountFn`. Call that function one time for each pair of an actor
+and a container.
 
 ## Parameters
 
-| Parameter        | Type                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `registryResult` | [`DefineRegistryResult`](../interfaces/DefineRegistryResult.md) | Result from `defineRegistry()` — provides the registry and the lazy handlers factory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `options`        | [`CreatePlayUIOptions`](../interfaces/CreatePlayUIOptions.md)   | Factory-level configuration (see [CreatePlayUIOptions](../interfaces/CreatePlayUIOptions.md)): - `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. - `fallback` — element shown when the actor's initial view is `null`. |
+| Parameter        | Type                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registryResult` | [`DefineRegistryResult`](../interfaces/DefineRegistryResult.md) | The result of `defineRegistry()`. It gives the registry and the factory of the handlers, which it builds late.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `options`        | [`CreatePlayUIOptions`](../interfaces/CreatePlayUIOptions.md)   | The factory configuration. See [CreatePlayUIOptions](../interfaces/CreatePlayUIOptions.md): - `functions` — the named compute functions of a `$computed` prop expression. - `directives` — your own dynamic values with a `$` prefix. The renderer resolves them with the props. - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`. - `navigate` — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`. - `onRenderError` — the `(error, name)` handler of a component render error and of an action handler rejection. - `fallback` — the element to show when the first view of the actor is `null`. |
 
 ## Returns
 
 [`MountFn`](../type-aliases/MountFn.md)
 
-`MountFn`: `(actor, container, mountOptions?) → disconnect`
+The `MountFn`: `(actor, container, mountOptions?) → disconnect`

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

@@ -6,12 +6,13 @@
 function createRenderer<C>(catalog, componentMap): (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-renderer.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-renderer.ts#L84)
+Defined in: [packages/play-dom/src/create-renderer.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-renderer.ts#L88)
 
-Create a reusable DOM renderer factory from a catalog and component map.
+Creates a DOM renderer factory from a catalog and a component map. You can use
+the factory more than one time.
 
-Returns a `mount(actor, container, options?)` function that wires up the
-PlayRenderer in one call and returns a `disconnect` cleanup function.
+It returns a `mount(actor, container, options?)` function. That function connects
+the PlayRenderer in one call, and it returns a `disconnect` cleanup function.
 
 ## Type Parameters
 
@@ -21,24 +22,27 @@ PlayRenderer in one call and returns a `disconnect` cleanup function.
 
 ## Parameters
 
-| Parameter      | Type                                                               | Description                                                      |
-| -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
-| `catalog`      | `C`                                                                | The json-render Catalog describing component and action schemas. |
-| `componentMap` | [`ComponentRegistry`](../type-aliases/ComponentRegistry.md)\<`C`\> | Component implementations keyed by catalog component name.       |
+| Parameter      | Type                                                               | Description                                                                            |
+| -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `catalog`      | `C`                                                                | The json-render Catalog. It describes the schema of each component and of each action. |
+| `componentMap` | [`ComponentRegistry`](../type-aliases/ComponentRegistry.md)\<`C`\> | The component implementations, with the catalog component name as the key.             |
 
 ## Returns
 
-A `mount` function that accepts `(actor, container, options?)` and returns `disconnect`.
+A `mount` function. It accepts `(actor, container, options?)`, and it returns `disconnect`.
 
 (`actor`, `container`, `options?`) => () => `void`
 
 ## Remarks
 
-`createRenderer` manages `registryResult` internally — it calls `defineRegistry` once and
-reuses the result across all `mount()` calls. The `mount` options type therefore excludes
-`registryResult` (it is always provided by `createRenderer` itself and cannot be overridden).
-
-If you need to call `registryResult.executeAction()` programmatically (outside the emit/on
-flow), or pass additional provider options (`navigate`, `onRenderError`, `functions`, etc.),
-use `createPlayUI` (which accepts the full `CreatePlayUIOptions`) or `defineRegistry` with
-`PlayRenderer` directly rather than `createRenderer`.
+`createRenderer` manages `registryResult` internally. It calls `defineRegistry`
+one time, and it uses that result in every `mount()` call. Therefore the options
+type of `mount` holds no `registryResult`: `createRenderer` always gives it, and
+you cannot replace it.
+
+Two situations need a different function. In the first, your code calls
+`registryResult.executeAction()` itself, outside the emit and on flow. In the
+second, you give more provider options, such as `navigate`, `onRenderError`, or
+`functions`. Use `createPlayUI`, which accepts the complete
+`CreatePlayUIOptions`. You can also use `defineRegistry` with `PlayRenderer`
+directly.

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

@@ -2,16 +2,16 @@
 
 # Interface: CreatePlayUIOptions
 
-Defined in: [packages/play-dom/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/types.ts#L67)
+Defined in: [packages/play-dom/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L69)
 
-Options for `createPlayUI()` — the batteries-included DOM factory.
+The options of `createPlayUI()`, the complete DOM factory.
 
-Extends [UIProviderOptions](UIProviderOptions.md), which contributes `functions`,
-`directives`, `validationFunctions`, `navigate`, and `onRenderError`. All
-are closed over at factory creation time and forwarded into `PlayRenderer`
-on every `mount()` call.
+This type extends [UIProviderOptions](UIProviderOptions.md), which gives `functions`,
+`directives`, `validationFunctions`, `navigate`, and `onRenderError`. The factory
+holds all of them from the moment of its creation, and it gives them to
+`PlayRenderer` on every `mount()` call.
 
-Parallel to `PlayUIProvider`'s props in the framework renderers.
+This type is parallel to the props of `PlayUIProvider` in the framework renderers.
 
 ## See
 
@@ -26,7 +26,7 @@ createPlayUI
 | Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Inherited from                                                                                                         | Defined in                                                                                                                       |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                     | [`UIProviderOptions`](UIProviderOptions.md).[`directives`](UIProviderOptions.md#property-directives)                   | -                                                                                                                                |
-| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| `null`                                                                                   | Optional fallback element shown when `currentView` is `null` on **initial mount** only. The fallback is appended immediately after `mount()` if the container is empty at that moment (i.e. the actor's initial view is `null`). **Limitation:** If the actor's view transitions to `null` after mount, the container will be cleared but this fallback will NOT be re-appended. For dynamic fallback behavior (null view after non-null), use `PlayRenderer` directly and wrap the `actor.currentView` signal to inject fallback content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                      | [packages/play-dom/src/types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/types.ts#L79) |
+| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| `null`                                                                                   | The optional fallback element. The factory shows it when `currentView` is `null` on the **first mount** only. The factory appends the fallback directly after `mount()`, when the container is empty at that moment, which means that the first view of the actor is `null`. **Limitation:** when the view of the actor becomes `null` after the mount, the renderer clears the container, and it does NOT append this fallback again. For a dynamic fallback, which follows a null view after a view that was not null, use `PlayRenderer` directly and wrap the `actor.currentView` signal to add the fallback content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                                                                                                      | [packages/play-dom/src/types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L82) |
 | <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | -                                                                                                                                |
 | <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                  | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | -                                                                                                                                |
 | <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`UIProviderOptions`](UIProviderOptions.md).[`onConfirm`](UIProviderOptions.md#property-onconfirm)                     | -                                                                                                                                |

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

@@ -2,17 +2,17 @@
 
 # Interface: MountOptions
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-play-ui.ts#L48)
+Defined in: [packages/play-dom/src/create-play-ui.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L49)
 
-Per-mount options passed to the `MountFn` returned by `createPlayUI`.
+The mount options of the `MountFn` that `createPlayUI` returns.
 
-These override or supplement the factory-level options on a per-actor/container
-basis. Factory-level options (`functions`, `validationFunctions`, `navigate`,
-`onRenderError`, `fallback`) are set once when calling `createPlayUI`.
+They replace or complete the factory options, for one actor and one container.
+The `createPlayUI` call sets the factory options (`functions`,
+`validationFunctions`, `navigate`, `onRenderError`, and `fallback`) one time.
 
 ## Properties
 
-| Property                                 | Type         | Description                                                                                                                                           | Defined in                                                                                                                                         |
-| ---------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-loading"></a> `loading?` | `boolean`    | When `true`, suppresses missing-child warnings during streaming spec ingestion and exposes `ctx.ctx.loading` to component implementations.            | [packages/play-dom/src/create-play-ui.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-play-ui.ts#L59) |
-| <a id="property-store"></a> `store?`     | `StateStore` | Optional external `StateStore` (controlled mode). When omitted, a fresh `@xstate/store` atom is created per view transition seeded from `spec.state`. | [packages/play-dom/src/create-play-ui.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-play-ui.ts#L54) |
+| Property                                 | Type         | Description                                                                                                                                                                              | Defined in                                                                                                                                         |
+| ---------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-loading"></a> `loading?` | `boolean`    | With the value `true`, the renderer stops each warning about an absent child during the ingestion of a streaming spec. It also gives `ctx.ctx.loading` to each component implementation. | [packages/play-dom/src/create-play-ui.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L61) |
+| <a id="property-store"></a> `store?`     | `StateStore` | The optional external `StateStore`, which is the controlled mode. Without it, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.   | [packages/play-dom/src/create-play-ui.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L55) |

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

@@ -2,14 +2,14 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/types.ts#L23)
+Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L23)
 
-Options for `PlayRenderer`.
+The options of `PlayRenderer`.
 
-Extends [UIProviderOptions](UIProviderOptions.md), which contributes `functions`,
-`directives`, `validationFunctions`, `navigate`, and `onRenderError`. All
-are forwarded into `DomRenderContext` on every render pass and are readable
-by component implementations via `ctx.ctx.*`.
+This type extends [UIProviderOptions](UIProviderOptions.md), which gives `functions`,
+`directives`, `validationFunctions`, `navigate`, and `onRenderError`. Each render
+pass puts all of them into `DomRenderContext`, and a component implementation
+reads them at `ctx.ctx.*`.
 
 ## Extends
 
@@ -21,10 +21,10 @@ by component implementations via `ctx.ctx.*`.
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                     | [`UIProviderOptions`](UIProviderOptions.md).[`directives`](UIProviderOptions.md#property-directives)                   | -                                                                                                                                |
 | <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | -                                                                                                                                |
-| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                 | When `true`, indicates the spec is still streaming (e.g. from an AI provider). Forwarded to `renderSpec` so component implementations can read `ctx.ctx.loading` to render skeleton states. Also suppresses missing-child warnings during stream ingestion, since referenced elements may not yet have arrived in the incremental spec. Mirrors the `loading` prop from framework renderer providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                      | [packages/play-dom/src/types.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/types.ts#L52) |
+| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                 | With the value `true`, the spec is still streaming, for example from an AI provider. The renderer gives the flag to `renderSpec`. A component implementation therefore reads `ctx.ctx.loading`, and it can render a skeleton state. The flag also stops each warning about an absent child during the ingestion of the stream, because an element of a reference can still be absent from the incremental spec. This option matches the `loading` prop of the framework renderer providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                      | [packages/play-dom/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L54) |
 | <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                  | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | -                                                                                                                                |
 | <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`UIProviderOptions`](UIProviderOptions.md).[`onConfirm`](UIProviderOptions.md#property-onconfirm)                     | -                                                                                                                                |
 | <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Unified error handler for component render errors and action handler rejections. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Invoked for three distinct error classes: - `(error, elementType)` — when a component renderer throws synchronously during `renderSpec` - `(error, actionName)` — when an action handler rejects during `emit()` (on-event path) - `(error, actionName)` — when an action handler rejects during a `watch` binding callback When provided, suppresses the `console.error` fallback for all three error types. Forwarded into `renderSpec` as the `onRenderError` parameter and into `DomRenderContext.onRenderError` so both `emit()` and `watch` handlers route their errors through the same channel as component render errors. **Example** `renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, });`                                                                                                                                                                                                                                               | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | -                                                                                                                                |
-| <a id="property-registryresult"></a> `registryResult?`           | [`DefineRegistryResult`](DefineRegistryResult.md)                                                         | The result from `defineRegistry` — provides both the registry and the handlers factory. When provided, `PlayRenderer` wires `setState` and `getState` from the @xstate/store-backed `StateStore` into the handlers factory automatically. This is the preferred approach as it ensures actions always receive live `setState` and `state` bound to the current store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                      | [packages/play-dom/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/types.ts#L31) |
-| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | Optional external StateStore (e.g. from `xstateStoreStateStore` in @xmachines/json-render-xstate). When provided, `PlayRenderer` operates in controlled mode — `spec.state` is ignored and this store is the single source of truth for UI state (form values, etc.). When omitted, a fresh `@xstate/store` atom is created internally per view transition, seeded from `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                      | [packages/play-dom/src/types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/types.ts#L41) |
+| <a id="property-registryresult"></a> `registryResult?`           | [`DefineRegistryResult`](DefineRegistryResult.md)                                                         | The result of `defineRegistry`. It gives the registry and the factory of the handlers. With this option, `PlayRenderer` connects `setState` and `getState` of the `StateStore` on @xstate/store to the factory of the handlers for you. This is the preferred way, because each action then always receives a live `setState` and a live `state` on the current store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                      | [packages/play-dom/src/types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L32) |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | The optional external StateStore, for example from `xstateStoreStateStore` in @xmachines/json-render-xstate. With this option, `PlayRenderer` works in the controlled mode: it ignores `spec.state`, and this store is the single source of truth of the UI state, such as a form value. Without this option, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                      | [packages/play-dom/src/types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L42) |
 | <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions for inline field validation. Each function receives `(value, args?)` and returns `true` (valid) or `false` (invalid). Functions are available to component implementations via `ctx.ctx.validationFunctions` and should be passed as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Mirrors `customFunctions` in `ValidationProvider` from the framework renderers. The DOM renderer has no automatic `ValidationProvider` tree — validation must be invoked explicitly by component implementations. **Example** `import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { validationFunctions: { isEven: (value) => typeof value === "number" && value % 2 === 0, phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)), }, }); // Inside a ComponentFn: const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => { const result = runValidationCheck( { type: "isEven", message: "must be even" }, { value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions }, ); // result.valid, result.message };` | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | -                                                                                                                                |

package/api/@xmachines/play-dom/type-aliases/MountFn.md

@@ -6,13 +6,13 @@
 type MountFn = (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom/src/create-play-ui.ts#L69)
+Defined in: [packages/play-dom/src/create-play-ui.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L71)
 
-The mount function returned by `createPlayUI`.
+The mount function that `createPlayUI` returns.
 
-Call with `(actor, container, mountOptions?)` to start the renderer.
-Returns a `disconnect` cleanup function that stops rendering and clears
-the container.
+Call it with `(actor, container, mountOptions?)` to start the renderer.
+It returns a `disconnect` cleanup function. That function stops the render and
+clears the container.
 
 ## Parameters