@xmachines/docs 1.0.0-beta.32 → 1.0.0-beta.34

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

@@ -0,0 +1,28 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / createPlayUI
+
+# Function: createPlayUI()
+
+```ts
+function createPlayUI(registryResult, options?): MountFn;
+```
+
+Defined in: [packages/play-dom/src/create-play-ui.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/create-play-ui.ts#L64)
+
+Create a batteries-included DOM renderer mount function.
+
+The user is responsible for calling defineRegistry to produce registryResult.
+createPlayUI closes over the registryResult and returns a mount function that
+can be called once per actor/container pair.
+
+## Parameters
+
+| Parameter        | Type                                                            | Description                                                                |
+| ---------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `registryResult` | [`DefineRegistryResult`](../interfaces/DefineRegistryResult.md) | Result from defineRegistry() containing registry + handlers factory.       |
+| `options`        | [`CreatePlayUIOptions`](../interfaces/CreatePlayUIOptions.md)   | Optional factory-level configuration (validationFunctions, navigate, etc.) |
+
+## Returns
+
+[`MountFn`](../type-aliases/MountFn.md)
+
+mount function: (actor, container, mountOptions?) → disconnect

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

@@ -0,0 +1,43 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / createRenderer
+
+# Function: createRenderer()
+
+```ts
+function createRenderer<C>(catalog, componentMap): (actor, container, options?) => () => void;
+```
+
+Defined in: [packages/play-dom/src/create-renderer.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/create-renderer.ts#L83)
+
+Create a reusable DOM renderer factory from a catalog and component map.
+
+Returns a `mount(actor, container, options?)` function that wires up the
+PlayRenderer in one call and returns a `disconnect` cleanup function.
+
+## Type Parameters
+
+| Type Parameter                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------ |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\> |
+
+## 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.       |
+
+## Returns
+
+A `mount` function that accepts `(actor, container, options?)` and 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 share the same `registryResult` with `connectRenderer`, use `defineRegistry` and
+`PlayRenderer` directly rather than `createRenderer`.

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

@@ -6,7 +6,7 @@
 function defineRegistry<C>(_catalog, options): DefineRegistryResult;
 ```
 
-Defined in: [json-render/types.ts:213](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L213)
+Defined in: [packages/play-dom/src/json-render/types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L391)
 
 Build a `DomRegistry` from a catalog and component/action options.
 
@@ -18,10 +18,10 @@ Build a `DomRegistry` from a catalog and component/action options.
 
 ## Parameters
 
-| Parameter  | Type                                                                     |
-| ---------- | ------------------------------------------------------------------------ |
-| `_catalog` | `C`                                                                      |
-| `options`  | [`DefineRegistryOptions`](../interfaces/DefineRegistryOptions.md)\<`C`\> |
+| Parameter  | Type                                                                       |
+| ---------- | -------------------------------------------------------------------------- |
+| `_catalog` | `C`                                                                        |
+| `options`  | [`DefineRegistryOptions`](../type-aliases/DefineRegistryOptions.md)\<`C`\> |
 
 ## Returns
 

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

@@ -3,10 +3,21 @@
 # Function: renderSpec()
 
 ```ts
-function renderSpec(spec, store, registry, send, handlers): Node | null;
+function renderSpec(
+	spec,
+	store,
+	registry,
+	send,
+	handlers,
+	fallback?,
+	onRenderError?,
+	functions?,
+	loading?,
+	onWatchSetup?,
+): Node | null;
 ```
 
-Defined in: [json-render/renderer.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/renderer.ts#L53)
+Defined in: [packages/play-dom/src/json-render/renderer.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/renderer.ts#L116)
 
 Render a Spec tree into DOM nodes using the provided `DomRegistry`.
 
@@ -19,13 +30,18 @@ built by `defineRegistry` — this function only orchestrates the traversal.
 
 ## Parameters
 
-| Parameter  | Type                                            | Description                                                  |
-| ---------- | ----------------------------------------------- | ------------------------------------------------------------ |
-| `spec`     | `Spec`                                          | The json-render `Spec` describing the UI tree.               |
-| `store`    | `StateStore`                                    | Live `StateStore` bound to `spec.state`.                     |
-| `registry` | [`DomRegistry`](../type-aliases/DomRegistry.md) | Map of element type names → `DomComponentRenderer`.          |
-| `send`     | (`event`) => `void`                             | Dispatcher for interaction events (e.g. actor.send).         |
-| `handlers` | `Record`\<`string`, `ActionHandler`\>           | Map of catalog action names → async ActionHandler functions. |
+| Parameter        | Type                                                              | Description                                                                                                                                                                                                                                                                            |
+| ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec`           | `Spec`                                                            | The json-render `Spec` describing the UI tree.                                                                                                                                                                                                                                         |
+| `store`          | `StateStore`                                                      | Live `StateStore` bound to `spec.state`.                                                                                                                                                                                                                                               |
+| `registry`       | [`DomRegistry`](../type-aliases/DomRegistry.md)                   | Map of element type names → `DomComponentRenderer`.                                                                                                                                                                                                                                    |
+| `send`           | (`event`) => `void`                                               | Dispatcher for interaction events (e.g. actor.send).                                                                                                                                                                                                                                   |
+| `handlers`       | `Record`\<`string`, `ActionHandler`\>                             | Map of catalog action names → async ActionHandler functions.                                                                                                                                                                                                                           |
+| `fallback?`      | [`DomComponentRenderer`](../type-aliases/DomComponentRenderer.md) | Optional renderer called when `registry` has no entry for an element's `type` (GAP-04). If absent, unknown types return `null`.                                                                                                                                                        |
+| `onRenderError?` | (`type`, `err`) => `void`                                         | Optional callback invoked with `(type, error)` when a component renderer throws (GAP-08). If absent, errors are logged via `console.error` with the prefix `[json-render] Rendering error in`.                                                                                         |
+| `functions?`     | `Record`\<`string`, `ComputedFunction`\>                          | Optional map of named compute functions forwarded to `PropResolutionContext` (GAP-03). Enables `{ $computed: "fn", args }` prop expressions to resolve. When absent, `$computed` expressions return `undefined` (backward-compatible, no throw).                                       |
+| `loading?`       | `boolean`                                                         | Optional flag indicating the spec is still streaming (GAP-06). When `true`, components can read `ctx.loading` to render skeleton states, and missing-child warnings (GAP-07) are suppressed since referenced elements may not yet have arrived in the incremental spec.                |
+| `onWatchSetup?`  | (`cleanup`) => `void`                                             | Optional callback invoked with each watch subscription cleanup function (GAP-02). When an element declares `watch`, the renderer sets up a store subscription and passes its unsubscribe function to this callback. Callers (e.g. PlayRenderer) collect these to call on disconnect(). |
 
 ## Returns
 
@@ -34,6 +50,24 @@ built by `defineRegistry` — this function only orchestrates the traversal.
 The root DOM `Node`, or `null` if the root is invisible
 or has no registered renderer.
 
+## Remarks
+
+**Devtools isolation in tests:** The module-level `_devtoolsActive` flag is a
+singleton that persists for the lifetime of the module. In test environments,
+any call to `markDevtoolsActive()` MUST be paired with a `release()` call
+inside a `try/finally` block. Failing to do so leaves `_devtoolsActive = true`
+for all subsequent tests, causing false positives in devtools-conditional
+rendering paths (e.g. `data-jr-key` wrapper spans).
+
+```ts
+const release = markDevtoolsActive();
+try {
+	// test code
+} finally {
+	release();
+}
+```
+
 ## Example
 
 ```ts

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

@@ -2,7 +2,7 @@
 
 # Interface: ComponentContext\<C, K\>
 
-Defined in: [json-render/types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L78)
+Defined in: [packages/play-dom/src/json-render/types.ts:181](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L181)
 
 ## Type Parameters
 
@@ -13,11 +13,11 @@ Defined in: [json-render/types.ts:78](https://gitlab.com/xmachin-es/xmachines-js
 
 ## Properties
 
-| Property                                  | Type                                          | Description                                                                      | Defined in                                                                                                                                   |
-| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. | [json-render/types.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L88)   |
-| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list.                            | [json-render/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L84)   |
-| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                        | [json-render/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L100) |
-| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                           | [json-render/types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L92)   |
-| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map.                 | [json-render/types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L96)   |
-| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                          | [json-render/types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L80)   |
+| Property                                  | Type                                          | Description                                                                      | Defined in                                                                                                                                                         |
+| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. | [packages/play-dom/src/json-render/types.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L191) |
+| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list.                            | [packages/play-dom/src/json-render/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L187) |
+| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                        | [packages/play-dom/src/json-render/types.ts:203](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L203) |
+| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                           | [packages/play-dom/src/json-render/types.ts:195](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L195) |
+| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map.                 | [packages/play-dom/src/json-render/types.ts:199](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L199) |
+| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                          | [packages/play-dom/src/json-render/types.ts:183](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L183) |

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

@@ -2,17 +2,27 @@
 
 # Interface: ConnectRendererOptions
 
-Defined in: [xm-types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L38)
+Defined in: [packages/play-dom/src/types.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L61)
 
 Options for connectRenderer() — backward compat API.
 
+## Extends
+
+- [`UIProviderOptions`](UIProviderOptions.md)
+
 ## Properties
 
-| Property                                    | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                   | Defined in                                                                                                               |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `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 instance with currentView signal (requires Viewable capability)                                                                                                                                                                                         | [xm-types.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L40) |
-| <a id="property-container"></a> `container` | `HTMLElement`                                                                                                                                                                                                                                                    | Container element to render into                                                                                                                                                                                                                              | [xm-types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L46) |
-| <a id="property-fallback"></a> `fallback?`  | `HTMLElement` \| `null`                                                                                                                                                                                                                                          | Optional element shown when currentView is null (defaults to nothing — clears container)                                                                                                                                                                      | [xm-types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L49) |
-| <a id="property-handlers"></a> `handlers?`  | `Record`\<`string`, `ActionHandler`\>                                                                                                                                                                                                                            | Map of catalog action name → async ActionHandler function. Replaces the old `actions: Record<string, string>` string-map approach.                                                                                                                            | [xm-types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L55) |
-| <a id="property-registry"></a> `registry`   | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Registry of component renderers — replaces old `components` map                                                                                                                                                                                               | [xm-types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L43) |
-| <a id="property-store"></a> `store?`        | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored. When omitted, a fresh @xstate/store atom is created internally per view transition. | [xm-types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L62) |
+| Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Inherited from                                                                                                         | Defined in                                                                                                                                                       |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `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 instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                      | [packages/play-dom/src/types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L63)                         |
+| <a id="property-container"></a> `container`                      | `HTMLElement`                                                                                                                                                                                                                                                    | Container element to render into                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                      | [packages/play-dom/src/types.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L87)                         |
+| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| `null`                                                                                                                                                                                                                                          | Optional element shown when `currentView` is `null` on **initial mount** only. The fallback is appended immediately after `renderer.connect()` 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:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L100)                       |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                                                                                                                                                                         | Custom computed functions available to `$computed` field expressions in specs. Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | [packages/play-dom/src/json-render/types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L80) |
+| <a id="property-handlers"></a> `handlers?`                       | `Record`\<`string`, `ActionHandler`\>                                                                                                                                                                                                                            | Pre-resolved handler map — for backward compatibility. Ignored when `registryResult` is provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                                                                                                      | [packages/play-dom/src/types.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L112)                       |
+| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                                                                                                                                                                        | When true, indicates the spec is still streaming (e.g. from an AI provider). Forwarded to PlayRenderer which threads it into renderSpec so components can read ctx.ctx.loading to show skeleton states. Also suppresses missing-child warnings. Mirrors the `loading` prop from framework renderer providers.                                                                                                                                                                                                                                                                                                                    | -                                                                                                                      | [packages/play-dom/src/types.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L127)                       |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | Navigation function forwarded to json-render computed functions that need to trigger programmatic navigation (e.g. a `navigate` action in the catalog).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | [packages/play-dom/src/json-render/types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L74) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Forwarded as `onRenderError` to the underlying renderer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | [packages/play-dom/src/json-render/types.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L86) |
+| <a id="property-registry"></a> `registry`                        | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Registry of component renderers — replaces old `components` map. When also providing `registryResult`, this **must** be the `.registry` field from the **same** `defineRegistry()` call to keep component renderers and action handlers aligned. Mixing a `registry` from one catalog with a `registryResult` from another will cause component wrappers and action handlers to be mismatched, producing silent runtime failures. **Example** `const registryResult = defineRegistry(catalog, { components, actions }); connectRenderer({ registry: registryResult.registry, // ← from the same call registryResult, // ... });` | -                                                                                                                      | [packages/play-dom/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L84)                         |
+| <a id="property-registryresult"></a> `registryResult?`           | [`DefineRegistryResult`](DefineRegistryResult.md)                                                                                                                                                                                                                | The result from `defineRegistry` — wires setState/getState from the xstate store into action handlers automatically. Preferred over `handlers` for new code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                                                                                                      | [packages/play-dom/src/types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L106)                       |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored. When omitted, a fresh @xstate/store atom is created internally per view transition.                                                                                                                                                                                                                                                                                                                                                                    | -                                                                                                                      | [packages/play-dom/src/types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L119)                       |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | Custom validation functions for the json-render ValidationProvider equivalent. Each function receives `(value, args?)` and returns a boolean.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | [packages/play-dom/src/json-render/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L68) |

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

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / CreatePlayUIOptions
+
+# Interface: CreatePlayUIOptions
+
+Defined in: [packages/play-dom/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L139)
+
+Options for createPlayUI() — the batteries-included DOM factory.
+
+Extends UIProviderOptions (shared configurable UI behaviours) with the
+DOM-specific `fallback` element. Parallel to PlayUIProvider's extra props
+in the framework renderers.
+
+## See
+
+createPlayUI
+
+## Extends
+
+- [`UIProviderOptions`](UIProviderOptions.md)
+
+## Properties
+
+| Property                                                         | Type                                                          | Description                                                                                                                                             | Inherited from                                                                                                         | Defined in                                                                                                                                                       |
+| ---------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| `null`                                       | Optional fallback element shown when currentView is null on initial mount. Forwarded to connectRenderer/PlayRenderer as the fallback.                   | -                                                                                                                      | [packages/play-dom/src/types.ts:144](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L144)                       |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                      | Custom computed functions available to `$computed` field expressions in specs. Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.     | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | [packages/play-dom/src/json-render/types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L80) |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                            | Navigation function forwarded to json-render computed functions that need to trigger programmatic navigation (e.g. a `navigate` action in the catalog). | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | [packages/play-dom/src/json-render/types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L74) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | Called when an individual catalog component throws during render. Forwarded as `onRenderError` to the underlying renderer.                              | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | [packages/play-dom/src/json-render/types.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L86) |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>         | Custom validation functions for the json-render ValidationProvider equivalent. Each function receives `(value, args?)` and returns a boolean.           | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | [packages/play-dom/src/json-render/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L68) |

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

@@ -2,16 +2,16 @@
 
 # Interface: DefineRegistryResult
 
-Defined in: [json-render/types.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L174)
+Defined in: [packages/play-dom/src/json-render/types.ts:331](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L331)
 
 Result returned by `defineRegistry`.
 
-Matches `DefineRegistryResult` from @json-render/react, /solid, /svelte, /vue —
-returns `{ registry, handlers }` instead of the old `{ registry, actorActions }`.
+Matches `DefineRegistryResult` from @json-render/react, /solid, /svelte, /vue.
 
 ## Properties
 
-| Property                                  | Type                                                                 | Description                                                                                                                                                                                                                                | Defined in                                                                                                                                   |
-| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-handlers"></a> `handlers` | (`getSetState`, `getState`) => `Record`\<`string`, `ActionHandler`\> | Create ActionProvider-compatible handlers. Accepts getter functions so handlers always read the latest state. For DOM rendering, pass `() => undefined, () => ({})` since DOM actions dispatch directly to actor without needing setState. | [json-render/types.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L185) |
-| <a id="property-registry"></a> `registry` | [`DomRegistry`](../type-aliases/DomRegistry.md)                      | The built `DomRegistry`, ready to pass to `connectRenderer` or `PlayRenderer`.                                                                                                                                                             | [json-render/types.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L178) |
+| Property                                            | Type                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                       | Defined in                                                                                                                                                         |
+| --------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-executeaction"></a> `executeAction` | (`actionName`, `params`, `setState`, `state?`) => `Promise`\<`void`\> | Execute a named action by name, with optional params. Mirrors `executeAction` on `DefineRegistryResult` from @json-render/react, /solid, /vue, /svelte. Useful for programmatically triggering actions outside of the emit/on flow.                                                                                                                                                               | [packages/play-dom/src/json-render/types.ts:361](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L361) |
+| <a id="property-handlers"></a> `handlers`           | (`getSetState`, `getState`) => `Record`\<`string`, `ActionHandler`\>  | Create ActionProvider-compatible handlers. Accepts getter functions (called lazily at action-invocation time) so handlers always see the latest setState and state snapshot — matching the pattern from the framework renderers. In `PlayRenderer`, these are wired automatically from the xstate store. Pass `() => undefined, () => ({})` only in tests or when state management is not needed. | [packages/play-dom/src/json-render/types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L346) |
+| <a id="property-registry"></a> `registry`           | [`DomRegistry`](../type-aliases/DomRegistry.md)                       | The built `DomRegistry`, ready to pass to `connectRenderer` or `PlayRenderer`.                                                                                                                                                                                                                                                                                                                    | [packages/play-dom/src/json-render/types.ts:335](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L335) |

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

@@ -2,17 +2,22 @@
 
 # Interface: DomRenderContext
 
-Defined in: [json-render/types.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L52)
+Defined in: [packages/play-dom/src/json-render/types.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L125)
 
 Low-level render context passed to each `DomComponentRenderer`.
 
 ## Properties
 
-| Property                                                 | Type                                  | Description                                                              | Defined in                                                                                                                                 |
-| -------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-elementbindings"></a> `elementBindings?` | `Record`\<`string`, `string`\>        | Pre-computed two-way binding paths for this element's props.             | [json-render/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L66) |
-| <a id="property-handlers"></a> `handlers`                | `Record`\<`string`, `ActionHandler`\> | Map of json-render catalog action names → async ActionHandler functions. | [json-render/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L60) |
-| <a id="property-renderchildren"></a> `renderChildren`    | (`keys`) => `Node`[]                  | Render a list of child element keys into DOM nodes.                      | [json-render/types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L62) |
-| <a id="property-send"></a> `send`                        | (`event`) => `void`                   | Dispatch an event (e.g. to an XState actor).                             | [json-render/types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L58) |
-| <a id="property-spec"></a> `spec`                        | `Spec`                                | Full spec tree for this render pass.                                     | [json-render/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L54) |
-| <a id="property-store"></a> `store`                      | `StateStore`                          | Live state store bound to `spec.state`.                                  | [json-render/types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L56) |
+| Property                                                 | Type                                     | Description                                                                                                                                                                                                                                                                  | Defined in                                                                                                                                                         |
+| -------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-elementbindings"></a> `elementBindings?` | `Record`\<`string`, `string`\>           | Pre-computed two-way binding paths for this element's props.                                                                                                                                                                                                                 | [packages/play-dom/src/json-render/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L139) |
+| <a id="property-functions"></a> `functions?`             | `Record`\<`string`, `ComputedFunction`\> | Optional map of named compute functions, forwarded to PropResolutionContext. Enables { $computed: "funcName", args: {...} } prop expressions to resolve. Mirrors the `functions` prop from framework renderer providers.                                                     | [packages/play-dom/src/json-render/types.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L146) |
+| <a id="property-handlers"></a> `handlers`                | `Record`\<`string`, `ActionHandler`\>    | Map of json-render catalog action names → async ActionHandler functions.                                                                                                                                                                                                     | [packages/play-dom/src/json-render/types.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L133) |
+| <a id="property-loading"></a> `loading?`                 | `boolean`                                | When true, indicates the spec is still streaming (e.g. from an AI provider). Component implementations can use this to show skeleton/loading states. When loading=true, missing-child warnings are suppressed. Mirrors the `loading` prop from framework renderer providers. | [packages/play-dom/src/json-render/types.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L154) |
+| <a id="property-renderchildren"></a> `renderChildren`    | (`keys`) => `Node`[]                     | Render a list of child element keys into DOM nodes.                                                                                                                                                                                                                          | [packages/play-dom/src/json-render/types.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L135) |
+| <a id="property-repeatbasepath"></a> `repeatBasePath?`   | `string`                                 | Absolute JSON Pointer path to the current repeat item (e.g. "/todos/0"). Mirrors `repeatBasePath` in `PropResolutionContext`.                                                                                                                                                | [packages/play-dom/src/json-render/types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L169) |
+| <a id="property-repeatindex"></a> `repeatIndex?`         | `number`                                 | Current repeat array index when inside a repeat scope. Mirrors `repeatIndex` in `PropResolutionContext`.                                                                                                                                                                     | [packages/play-dom/src/json-render/types.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L164) |
+| <a id="property-repeatitem"></a> `repeatItem?`           | `unknown`                                | Current repeat item when inside a repeat scope. Mirrors `repeatItem` in `@json-render/core`'s `PropResolutionContext`.                                                                                                                                                       | [packages/play-dom/src/json-render/types.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L159) |
+| <a id="property-send"></a> `send`                        | (`event`) => `void`                      | Dispatch an event (e.g. to an XState actor).                                                                                                                                                                                                                                 | [packages/play-dom/src/json-render/types.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L131) |
+| <a id="property-spec"></a> `spec`                        | `Spec`                                   | Full spec tree for this render pass.                                                                                                                                                                                                                                         | [packages/play-dom/src/json-render/types.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L127) |
+| <a id="property-store"></a> `store`                      | `StateStore`                             | Live state store bound to `spec.state`.                                                                                                                                                                                                                                      | [packages/play-dom/src/json-render/types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L129) |

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

@@ -2,14 +2,14 @@
 
 # Interface: EventHandle
 
-Defined in: [json-render/types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L36)
+Defined in: [packages/play-dom/src/json-render/types.ts:109](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L109)
 
 Handle returned by `ComponentContext.on(eventName)`.
 
 ## Properties
 
-| Property                                                          | Type         | Description                                                              | Defined in                                                                                                                                 |
-| ----------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-bound"></a> `bound`                               | `boolean`    | `true` if an `on` binding exists for this event name; `false` otherwise. | [json-render/types.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L44) |
-| <a id="property-emit"></a> `emit`                                 | () => `void` | Fire the bound action, resolving params from the current state store.    | [json-render/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L38) |
-| <a id="property-shouldpreventdefault"></a> `shouldPreventDefault` | `boolean`    | Whether any binding for this event has `preventDefault: true`.           | [json-render/types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L42) |
+| Property                                                          | Type         | Description                                                              | Defined in                                                                                                                                                         |
+| ----------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-bound"></a> `bound`                               | `boolean`    | `true` if an `on` binding exists for this event name; `false` otherwise. | [packages/play-dom/src/json-render/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L117) |
+| <a id="property-emit"></a> `emit`                                 | () => `void` | Fire the bound action, resolving params from the current state store.    | [packages/play-dom/src/json-render/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L111) |
+| <a id="property-shouldpreventdefault"></a> `shouldPreventDefault` | `boolean`    | Whether any binding for this event has `preventDefault: true`.           | [packages/play-dom/src/json-render/types.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L115) |

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

@@ -0,0 +1,14 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / MountOptions
+
+# Interface: MountOptions
+
+Defined in: [packages/play-dom/src/create-play-ui.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/create-play-ui.ts#L35)
+
+Per-mount options that can override factory-level settings.
+
+## Properties
+
+| Property                                 | Type         | Description                                                                                     | Defined in                                                                                                                                                 |
+| ---------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-loading"></a> `loading?` | `boolean`    | When true, suppresses missing-child warnings during streaming spec ingestion.                   | [packages/play-dom/src/create-play-ui.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/create-play-ui.ts#L39) |
+| <a id="property-store"></a> `store?`     | `StateStore` | Optional external StateStore (controlled mode). When omitted, a fresh atom is created per view. | [packages/play-dom/src/create-play-ui.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/create-play-ui.ts#L37) |

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

@@ -2,13 +2,15 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [xm-types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L18)
+Defined in: [packages/play-dom/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L20)
 
 Options for PlayRenderer.
 
 ## Properties
 
-| Property                                   | Type                                  | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                               |
-| ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-handlers"></a> `handlers?` | `Record`\<`string`, `ActionHandler`\> | Map of catalog action name → async ActionHandler function. Replaces the old `actions: Record<string, string>` string-map approach.                                                                                                                                                                                                                                  | [xm-types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L23) |
-| <a id="property-store"></a> `store?`       | `StateStore`                          | Optional external StateStore (e.g. from `xstateStoreStateStore` in @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. | [xm-types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L32) |
+| Property                                               | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers?`             | `Record`\<`string`, `ActionHandler`\>             | Pre-resolved handler map — for backward compatibility or advanced use cases. When `registryResult` is provided, this is ignored. If you need actions to receive `setState` and `state`, use `registryResult` instead.                                                                                                                                                                                     | [packages/play-dom/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L38) |
+| <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 ComponentFn implementations can read ctx.ctx.loading to show skeleton states. Also suppresses missing-child warnings during stream ingestion. Mirrors the `loading` prop from framework renderer providers.                                                                                       | [packages/play-dom/src/types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L55) |
+| <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. Mutually exclusive with `handlers`. | [packages/play-dom/src/types.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L30) |
+| <a id="property-store"></a> `store?`                   | `StateStore`                                      | Optional external StateStore (e.g. from `xstateStoreStateStore` in @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:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/types.ts#L47) |

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

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / UIProviderOptions
+
+# Interface: UIProviderOptions
+
+Defined in: [packages/play-dom/src/json-render/types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L63)
+
+Shared UI-provider options — the configurable rendering behaviours that sit
+above the core actor/registry wiring.
+
+These fields mirror the forwarded props on `JSONUIProvider` /
+`JsonUIProvider` across @json-render/react, /vue, /solid, /svelte.
+Grouping them here lets `ConnectRendererOptions` and `CreatePlayUIOptions`
+in `types.ts` extend a single source of truth.
+
+## Extended by
+
+- [`ConnectRendererOptions`](ConnectRendererOptions.md)
+- [`CreatePlayUIOptions`](CreatePlayUIOptions.md)
+
+## Properties
+
+| Property                                                         | Type                                                          | Description                                                                                                                                             | Defined in                                                                                                                                                       |
+| ---------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                      | Custom computed functions available to `$computed` field expressions in specs. Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.     | [packages/play-dom/src/json-render/types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L80) |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                            | Navigation function forwarded to json-render computed functions that need to trigger programmatic navigation (e.g. a `navigate` action in the catalog). | [packages/play-dom/src/json-render/types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L74) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | Called when an individual catalog component throws during render. Forwarded as `onRenderError` to the underlying renderer.                              | [packages/play-dom/src/json-render/types.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L86) |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>         | Custom validation functions for the json-render ValidationProvider equivalent. Each function receives `(value, args?)` and returns a boolean.           | [packages/play-dom/src/json-render/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L68) |