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

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

@@ -2,34 +2,42 @@
 
 # Class: PlayRenderer
 
-Defined in: [PlayRenderer.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L60)
+Defined in: [PlayRenderer.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/PlayRenderer.ts#L78)
 
-PlayRenderer connects an actor's currentView signal to the DOM renderer.
+PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
 
-Usage:
+Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
+functions into `container` on every view transition. Cleared on `disconnect()`.
+
+**Preferred usage — via `registryResult`:**
 
 ```typescript
-const { registry, handlers } = defineRegistry(catalog, { components, actions });
-const resolvedHandlers = handlers(
-	() => undefined,
-	() => ({}),
-);
-const renderer = new PlayRenderer(container, actor, registry, { handlers: resolvedHandlers });
+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
+});
 renderer.connect();
+// Later:
+renderer.disconnect();
+```
+
+**Controlled store mode** — bring your own `StateStore`:
 
-// Controlled mode — bring your own store:
+```typescript
 import { createAtom } from "@xstate/store";
 import { xstateStoreStateStore } from "@json-render/xstate";
-const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
-const renderer = new PlayRenderer(container, actor, registry, {
-	store,
-	handlers: resolvedHandlers,
-});
 
-// Later:
-renderer.disconnect();
+const atom = createAtom({ username: "" });
+const store = xstateStoreStateStore({ atom });
+const renderer = new PlayRenderer(container, actor, registry, { registryResult, store });
+renderer.connect();
 ```
 
+Double `connect()` is safe — calling `connect()` while already connected
+automatically disconnects first, preventing double-render subscriptions.
+
 ## Constructors
 
 ### Constructor
@@ -42,16 +50,16 @@ new PlayRenderer(
    options?): PlayRenderer;
 ```
 
-Defined in: [PlayRenderer.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L72)
+Defined in: [PlayRenderer.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/PlayRenderer.ts#L101)
 
 #### Parameters
 
-| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | The `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 instance providing the `currentView` signal (must implement `Viewable`).                                                                                                                                             |
-| `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Map of component type names to `DomComponentRenderer` functions.                                                                                                                                                           |
-| `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)                                                                                                                                                                                                              | Optional configuration: `handlers` map (action name → async handler) and optional external `store` (controlled mode — when omitted, a fresh `@xstate/store` atom is created per view transition seeded from `spec.state`). |
+| 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: - `registryResult` — preferred; auto-wires `setState`/`state` from the xstate store. - `handlers` — pre-resolved handler map (legacy; used when `registryResult` is absent). - `store` — external `StateStore` (controlled mode; overrides `spec.state` seeding). - `loading` — streaming mode flag; suppresses missing-child warnings. |
 
 #### Returns
 
@@ -65,11 +73,16 @@ Defined in: [PlayRenderer.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/bl
 connect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L83)
+Defined in: [PlayRenderer.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/PlayRenderer.ts#L117)
 
 Start watching actor.currentView and render to container.
 Renders the initial view synchronously, then subscribes to 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.
+
 #### Returns
 
 `void`
@@ -82,7 +95,7 @@ Renders the initial view synchronously, then subscribes to signal changes.
 disconnect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L91)
+Defined in: [PlayRenderer.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/PlayRenderer.ts#L126)
 
 Stop watching and clear the container.
 

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

@@ -6,46 +6,65 @@
 function connectRenderer(options): () => void;
 ```
 
-Defined in: [connect-renderer.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/connect-renderer.ts#L46)
+Defined in: [connect-renderer.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/connect-renderer.ts#L65)
 
-Connect a signal-driven DOM renderer to an actor's currentView signal.
+Connect a signal-driven DOM renderer to an actor's `currentView` signal.
 
-Subscribes to `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
-functions into the provided `container` element on every state change.
+Subscribes to `actor.currentView` via TC39 Signals and renders catalog-typed
+components into `container` on every view transition. Clears the container
+when the view is `null` (optionally appends `fallback` on initial mount).
 
-- Renders the initial view immediately (synchronous)
-- Re-renders when `actor.currentView` signal changes (via microtask)
-- Clears container when view is `null` (optionally appends fallback)
+- Initial render is **synchronous** — the container is populated before `connectRenderer` returns.
+- Signal-driven re-renders are **microtask-deferred** — `watchSignal` schedules them
+  on the next microtask queue tick, not synchronously within the signal update.
+
+For the one-call pattern, prefer [createRenderer](createRenderer.md) which wraps `defineRegistry`
+and `PlayRenderer` into a single factory function.
 
 ## Parameters
 
-| Parameter | Type                                                                | Description            |
-| --------- | ------------------------------------------------------------------- | ---------------------- |
-| `options` | [`ConnectRendererOptions`](../interfaces/ConnectRendererOptions.md) | ConnectRendererOptions |
+| Parameter | Type                                                                | Description                                                       |
+| --------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `options` | [`ConnectRendererOptions`](../interfaces/ConnectRendererOptions.md) | [ConnectRendererOptions](../interfaces/ConnectRendererOptions.md) |
 
 ## Returns
 
-A cleanup function that stops all DOM mutations
+A cleanup function — call to stop all DOM mutations and remove subscriptions.
 
 () => `void`
 
 ## Example
 
 ```typescript
-import { connectRenderer, type DomComponentRenderer } from "@xmachines/play-dom";
+import { connectRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
 
-const unwatch = connectRenderer({
-	actor,
-	registry: {
-		Home: (element, ctx) => {
-			const el = document.createElement("div");
-			el.textContent = element.props.title as string;
+const catalog = defineCatalog(schema, {
+	components: { Home: { props: z.object({ title: z.string() }) } },
+	actions: { logout: {} },
+});
+
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: ({ props }) => {
+			const el = document.createElement("section");
+			el.textContent = props.title;
 			return el;
 		},
 	},
+	actions: {
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+
+const disconnect = connectRenderer({
+	actor,
+	registry: registryResult.registry,
+	registryResult, // preferred — wires setState/state from xstate store automatically
 	container: document.getElementById("app")!,
 });
 
-// Later: stop watching
-unwatch();
+// Later:
+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: [create-renderer.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/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: [json-render/types.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L351)
 
 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: [json-render/renderer.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/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: [json-render/types.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L141)
 
 ## Type Parameters
 
@@ -15,9 +15,9 @@ Defined in: [json-render/types.ts:78](https://gitlab.com/xmachin-es/xmachines-js
 
 | 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)   |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. | [json-render/types.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L151) |
+| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list.                            | [json-render/types.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L147) |
+| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                        | [json-render/types.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L163) |
+| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                           | [json-render/types.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L155) |
+| <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:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L159) |
+| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                          | [json-render/types.ts:143](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L143) |

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

@@ -2,17 +2,19 @@
 
 # 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: [xm-types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L59)
 
 Options for connectRenderer() — backward compat API.
 
 ## 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | 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:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L61)   |
+| <a id="property-container"></a> `container`            | `HTMLElement`                                                                                                                                                                                                                                                    | Container element to render into                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [xm-types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L85)   |
+| <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.                                                                                     | [xm-types.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L98)   |
+| <a id="property-handlers"></a> `handlers?`             | `Record`\<`string`, `ActionHandler`\>                                                                                                                                                                                                                            | Pre-resolved handler map — for backward compatibility. Ignored when `registryResult` is provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [xm-types.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L110) |
+| <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.                                                                                                                                                                                                                                                                                                                    | [xm-types.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L125) |
+| <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, // ... });` | [xm-types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L82)   |
+| <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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [xm-types.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L104) |
+| <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:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L117) |

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: [json-render/types.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L291)
 
 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.                                                                                                                                                               | [json-render/types.ts:321](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L321) |
+| <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. | [json-render/types.ts:306](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L306) |
+| <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:295](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L295) |

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: [json-render/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L85)
 
 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.                                                                                                                                                                                                                 | [json-render/types.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L99)   |
+| <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.                                                     | [json-render/types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L106) |
+| <a id="property-handlers"></a> `handlers`                | `Record`\<`string`, `ActionHandler`\>    | Map of json-render catalog action names → async ActionHandler functions.                                                                                                                                                                                                     | [json-render/types.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L93)   |
+| <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. | [json-render/types.ts:114](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L114) |
+| <a id="property-renderchildren"></a> `renderChildren`    | (`keys`) => `Node`[]                     | Render a list of child element keys into DOM nodes.                                                                                                                                                                                                                          | [json-render/types.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L95)   |
+| <a id="property-repeatbasepath"></a> `repeatBasePath?`   | `string`                                 | Absolute JSON Pointer path to the current repeat item (e.g. "/todos/0"). Mirrors `repeatBasePath` in `PropResolutionContext`.                                                                                                                                                | [json-render/types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L129) |
+| <a id="property-repeatindex"></a> `repeatIndex?`         | `number`                                 | Current repeat array index when inside a repeat scope. Mirrors `repeatIndex` in `PropResolutionContext`.                                                                                                                                                                     | [json-render/types.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L124) |
+| <a id="property-repeatitem"></a> `repeatItem?`           | `unknown`                                | Current repeat item when inside a repeat scope. Mirrors `repeatItem` in `@json-render/core`'s `PropResolutionContext`.                                                                                                                                                       | [json-render/types.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L119) |
+| <a id="property-send"></a> `send`                        | (`event`) => `void`                      | Dispatch an event (e.g. to an XState actor).                                                                                                                                                                                                                                 | [json-render/types.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L91)   |
+| <a id="property-spec"></a> `spec`                        | `Spec`                                   | Full spec tree for this render pass.                                                                                                                                                                                                                                         | [json-render/types.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L87)   |
+| <a id="property-store"></a> `store`                      | `StateStore`                             | Live state store bound to `spec.state`.                                                                                                                                                                                                                                      | [json-render/types.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L89)   |

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

@@ -2,7 +2,7 @@
 
 # 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: [json-render/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L69)
 
 Handle returned by `ComponentContext.on(eventName)`.
 
@@ -10,6 +10,6 @@ Handle returned by `ComponentContext.on(eventName)`.
 
 | 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) |
+| <a id="property-bound"></a> `bound`                               | `boolean`    | `true` if an `on` binding exists for this event name; `false` otherwise. | [json-render/types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L77) |
+| <a id="property-emit"></a> `emit`                                 | () => `void` | Fire the bound action, resolving params from the current state store.    | [json-render/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L71) |
+| <a id="property-shouldpreventdefault"></a> `shouldPreventDefault` | `boolean`    | Whether any binding for this event has `preventDefault: true`.           | [json-render/types.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L75) |