@xmachines/docs 1.0.0-beta.27 → 1.0.0-beta.28

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

@@ -2,7 +2,7 @@
 
 # Interface: ComponentContext\<C, K\>
 
-Defined in: [json-render/types.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L152)
+Defined in: [json-render/types.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L152)
 
 Catalog-typed context passed to each DOM component function.
 
@@ -54,9 +54,9 @@ const Login: ComponentFn<AuthCatalog, "Login"> = ({ props, emit, on, bindings })
 
 | 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. Keys match prop names that had `$bindState`/`$bindItem` expressions in the spec; values are the absolute state-store paths to write back to on user input. `undefined` when no bindings were found for this element.                                                                    | [json-render/types.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L168) |
-| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list. Append these into the returned element where children should appear.                                                                                                                                                                                                                                               | [json-render/types.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L159) |
-| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context. Exposes `send`, `store`, `actorActions`, and `renderChildren` for advanced use cases. Framework renderers do not expose this field — prefer `emit`/`on` for event dispatch and `children` for child rendering.                                                                                                                                 | [json-render/types.ts:206](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L206) |
-| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map. Resolves the catalog action binding, applies param expressions against the current state store, and calls `send()` with the mapped XState event type. **Example** `btn.addEventListener("click", () => emit("submit"));`                                                                                          | [json-render/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L180) |
-| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map. Use when you need `shouldPreventDefault` or want to check whether an `on` binding exists before attaching a listener. **Example** `const handle = on("submit"); if (handle.bound) { form.addEventListener("submit", (e) => { if (handle.shouldPreventDefault) e.preventDefault(); handle.emit(); }); }` | [json-render/types.ts:198](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L198) |
-| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                                                                                                                                                                                                                                                                                                                  | [json-render/types.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L154) |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. Keys match prop names that had `$bindState`/`$bindItem` expressions in the spec; values are the absolute state-store paths to write back to on user input. `undefined` when no bindings were found for this element.                                                                    | [json-render/types.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L168) |
+| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list. Append these into the returned element where children should appear.                                                                                                                                                                                                                                               | [json-render/types.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L159) |
+| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context. Exposes `send`, `store`, `actorActions`, and `renderChildren` for advanced use cases. Framework renderers do not expose this field — prefer `emit`/`on` for event dispatch and `children` for child rendering.                                                                                                                                 | [json-render/types.ts:206](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L206) |
+| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map. Resolves the catalog action binding, applies param expressions against the current state store, and calls `send()` with the mapped XState event type. **Example** `btn.addEventListener("click", () => emit("submit"));`                                                                                          | [json-render/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L180) |
+| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map. Use when you need `shouldPreventDefault` or want to check whether an `on` binding exists before attaching a listener. **Example** `const handle = on("submit"); if (handle.bound) { form.addEventListener("submit", (e) => { if (handle.shouldPreventDefault) e.preventDefault(); handle.emit(); }); }` | [json-render/types.ts:198](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L198) |
+| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                                                                                                                                                                                                                                                                                                                  | [json-render/types.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L154) |

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

@@ -2,7 +2,7 @@
 
 # Interface: ConnectRendererOptions
 
-Defined in: [xm-types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L35)
+Defined in: [xm-types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L35)
 
 Options for connectRenderer() — backward compat API.
 
@@ -10,9 +10,9 @@ Options for connectRenderer() — backward compat API.
 
 | Property                                    | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                   | Defined in                                                                                                               |
 | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actions"></a> `actions?`    | `Record`\<`string`, `string`\>                                                                                                                                                                                                                                   | Map of json-render actionName → XState event type                                                                                                                                                                                                             | [xm-types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L49) |
-| <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:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L37) |
-| <a id="property-container"></a> `container` | `HTMLElement`                                                                                                                                                                                                                                                    | Container element to render into                                                                                                                                                                                                                              | [xm-types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L43) |
-| <a id="property-fallback"></a> `fallback?`  | `HTMLElement` \| `null`                                                                                                                                                                                                                                          | Optional element shown when currentView is null (defaults to nothing — clears container)                                                                                                                                                                      | [xm-types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L46) |
-| <a id="property-registry"></a> `registry`   | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Registry of component renderers — replaces old `components` map                                                                                                                                                                                               | [xm-types.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L40) |
-| <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:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L56) |
+| <a id="property-actions"></a> `actions?`    | `Record`\<`string`, `string`\>                                                                                                                                                                                                                                   | Map of json-render actionName → XState event type                                                                                                                                                                                                             | [xm-types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L49) |
+| <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:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L37) |
+| <a id="property-container"></a> `container` | `HTMLElement`                                                                                                                                                                                                                                                    | Container element to render into                                                                                                                                                                                                                              | [xm-types.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L43) |
+| <a id="property-fallback"></a> `fallback?`  | `HTMLElement` \| `null`                                                                                                                                                                                                                                          | Optional element shown when currentView is null (defaults to nothing — clears container)                                                                                                                                                                      | [xm-types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L46) |
+| <a id="property-registry"></a> `registry`   | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Registry of component renderers — replaces old `components` map                                                                                                                                                                                               | [xm-types.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L40) |
+| <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:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L56) |

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

@@ -2,7 +2,7 @@
 
 # Interface: DefineRegistryOptions\<C\>
 
-Defined in: [json-render/types.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L275)
+Defined in: [json-render/types.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L275)
 
 Options for `defineRegistry`.
 
@@ -21,5 +21,5 @@ directly via `send()` to an XState actor instead of calling framework action han
 
 | Property                                       | Type                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Defined in                                                                                                                                   |
 | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actions"></a> `actions?`       | `InferCatalogActions`\<`C`\> _extends_ `Record`\<`string`, `never`\> ? `Record`\<`string`, `string`\> : `Record`\<keyof `InferCatalogActions`\<`C`\>, `string`\> | Map of catalog action name → XState event type string. When a spec element fires `emit("login")`, the DOM renderer looks up `actions.login` (e.g. `"auth.login"`) and calls `send({ type: "auth.login", ...params })`. In the framework renderers this field holds async handler functions. In the DOM renderer it is a simpler string map because routing to the actor is handled by the XMachines play-dom layer rather than inside the json-render action system. | [json-render/types.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L291) |
-| <a id="property-components"></a> `components?` | [`ComponentRegistry`](../type-aliases/ComponentRegistry.md)\<`C`\>                                                                                               | Catalog-typed component implementations. Each key must match a component declared in the catalog.                                                                                                                                                                                                                                                                                                                                                                    | [json-render/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L280) |
+| <a id="property-actions"></a> `actions?`       | `InferCatalogActions`\<`C`\> _extends_ `Record`\<`string`, `never`\> ? `Record`\<`string`, `string`\> : `Record`\<keyof `InferCatalogActions`\<`C`\>, `string`\> | Map of catalog action name → XState event type string. When a spec element fires `emit("login")`, the DOM renderer looks up `actions.login` (e.g. `"auth.login"`) and calls `send({ type: "auth.login", ...params })`. In the framework renderers this field holds async handler functions. In the DOM renderer it is a simpler string map because routing to the actor is handled by the XMachines play-dom layer rather than inside the json-render action system. | [json-render/types.ts:291](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L291) |
+| <a id="property-components"></a> `components?` | [`ComponentRegistry`](../type-aliases/ComponentRegistry.md)\<`C`\>                                                                                               | Catalog-typed component implementations. Each key must match a component declared in the catalog.                                                                                                                                                                                                                                                                                                                                                                    | [json-render/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L280) |

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

@@ -2,7 +2,7 @@
 
 # Interface: DefineRegistryResult
 
-Defined in: [json-render/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L303)
+Defined in: [json-render/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L303)
 
 Result returned by `defineRegistry`.
 
@@ -14,5 +14,5 @@ callers can pass it directly to `connectRenderer` or `PlayRenderer`.
 
 | Property                                          | Type                                            | Description                                                                                                                                                                                             | Defined in                                                                                                                                   |
 | ------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actoractions"></a> `actorActions` | `Record`\<`string`, `string`\>                  | Resolved map of catalog action name → XState event type string. Pass to `connectRenderer({ ..., actions: actorActions })` or `new PlayRenderer(container, actor, registry, { actions: actorActions })`. | [json-render/types.ts:314](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L314) |
-| <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:307](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L307) |
+| <a id="property-actoractions"></a> `actorActions` | `Record`\<`string`, `string`\>                  | Resolved map of catalog action name → XState event type string. Pass to `connectRenderer({ ..., actions: actorActions })` or `new PlayRenderer(container, actor, registry, { actions: actorActions })`. | [json-render/types.ts:314](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L314) |
+| <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:307](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L307) |

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

@@ -2,7 +2,7 @@
 
 # Interface: DomRenderContext
 
-Defined in: [json-render/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L68)
+Defined in: [json-render/types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L68)
 
 Low-level render context passed to each `DomComponentRenderer`.
 
@@ -13,9 +13,9 @@ the higher-level `ComponentContext<C, K>` provided by `defineRegistry`.
 
 | Property                                                 | Type                           | Description                                                                                                                                                                                                                                             | Defined in                                                                                                                                 |
 | -------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actoractions"></a> `actorActions`        | `Record`\<`string`, `string`\> | Map of json-render catalog action names → dispatch event type strings.                                                                                                                                                                                  | [json-render/types.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L76) |
-| <a id="property-elementbindings"></a> `elementBindings?` | `Record`\<`string`, `string`\> | Pre-computed two-way binding paths for this element's props. Resolved from raw props before `resolveElementProps` runs — the resolved props no longer contain `$bindState`/`$bindItem` expressions. `undefined` when no binding expressions were found. | [json-render/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L85) |
-| <a id="property-renderchildren"></a> `renderChildren`    | (`keys`) => `Node`[]           | Render a list of child element keys into DOM nodes.                                                                                                                                                                                                     | [json-render/types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L78) |
-| <a id="property-send"></a> `send`                        | (`event`) => `void`            | Dispatch an event (e.g. to an XState actor).                                                                                                                                                                                                            | [json-render/types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L74) |
-| <a id="property-spec"></a> `spec`                        | `Spec`                         | Full spec tree for this render pass.                                                                                                                                                                                                                    | [json-render/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L70) |
-| <a id="property-store"></a> `store`                      | `StateStore`                   | Live state store bound to `spec.state`.                                                                                                                                                                                                                 | [json-render/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L72) |
+| <a id="property-actoractions"></a> `actorActions`        | `Record`\<`string`, `string`\> | Map of json-render catalog action names → dispatch event type strings.                                                                                                                                                                                  | [json-render/types.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L76) |
+| <a id="property-elementbindings"></a> `elementBindings?` | `Record`\<`string`, `string`\> | Pre-computed two-way binding paths for this element's props. Resolved from raw props before `resolveElementProps` runs — the resolved props no longer contain `$bindState`/`$bindItem` expressions. `undefined` when no binding expressions were found. | [json-render/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L85) |
+| <a id="property-renderchildren"></a> `renderChildren`    | (`keys`) => `Node`[]           | Render a list of child element keys into DOM nodes.                                                                                                                                                                                                     | [json-render/types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L78) |
+| <a id="property-send"></a> `send`                        | (`event`) => `void`            | Dispatch an event (e.g. to an XState actor).                                                                                                                                                                                                            | [json-render/types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L74) |
+| <a id="property-spec"></a> `spec`                        | `Spec`                         | Full spec tree for this render pass.                                                                                                                                                                                                                    | [json-render/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L70) |
+| <a id="property-store"></a> `store`                      | `StateStore`                   | Live state store bound to `spec.state`.                                                                                                                                                                                                                 | [json-render/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L72) |

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

@@ -2,7 +2,7 @@
 
 # Interface: EventHandle
 
-Defined in: [json-render/types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L48)
+Defined in: [json-render/types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L48)
 
 Handle returned by `ComponentContext.on(eventName)`.
 
@@ -24,6 +24,6 @@ if (handle.bound) {
 
 | 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:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L57) |
-| <a id="property-emit"></a> `emit`                                 | () => `void` | Fire the bound action, resolving params from the current state store.                                                        | [json-render/types.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L50) |
-| <a id="property-shouldpreventdefault"></a> `shouldPreventDefault` | `boolean`    | Whether any binding for this event has `preventDefault: true`. Use to call `e.preventDefault()` on the triggering DOM event. | [json-render/types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L55) |
+| <a id="property-bound"></a> `bound`                               | `boolean`    | `true` if an `on` binding exists for this event name; `false` otherwise.                                                     | [json-render/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L57) |
+| <a id="property-emit"></a> `emit`                                 | () => `void` | Fire the bound action, resolving params from the current state store.                                                        | [json-render/types.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L50) |
+| <a id="property-shouldpreventdefault"></a> `shouldPreventDefault` | `boolean`    | Whether any binding for this event has `preventDefault: true`. Use to call `e.preventDefault()` on the triggering DOM event. | [json-render/types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L55) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [xm-types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L18)
+Defined in: [xm-types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L18)
 
 Options for PlayRenderer.
 
@@ -10,5 +10,5 @@ Options for PlayRenderer.
 
 | Property                                 | Type                           | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                               |
 | ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actions"></a> `actions?` | `Record`\<`string`, `string`\> | Map of json-render actionName → XState event type                                                                                                                                                                                                                                                                                                                   | [xm-types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L20) |
-| <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:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/xm-types.ts#L29) |
+| <a id="property-actions"></a> `actions?` | `Record`\<`string`, `string`\> | Map of json-render actionName → XState event type                                                                                                                                                                                                                                                                                                                   | [xm-types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L20) |
+| <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:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/xm-types.ts#L29) |

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

@@ -6,7 +6,7 @@
 type ComponentFn<C, K> = (ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [json-render/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L238)
+Defined in: [json-render/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L238)
 
 Catalog-typed DOM component function.
 

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

@@ -6,7 +6,7 @@
 type ComponentRegistry<C> = { [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K> };
 ```
 
-Defined in: [json-render/types.ts:251](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L251)
+Defined in: [json-render/types.ts:251](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L251)
 
 Catalog-keyed map of `ComponentFn` implementations.
 

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

@@ -6,7 +6,7 @@
 type DomComponentRenderer = (element, ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [json-render/types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L106)
+Defined in: [json-render/types.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L106)
 
 Raw DOM component renderer function.
 

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

@@ -6,7 +6,7 @@
 type DomRegistry = Record<string, DomComponentRenderer>;
 ```
 
-Defined in: [json-render/types.ts:263](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom/src/json-render/types.ts#L263)
+Defined in: [json-render/types.ts:263](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L263)
 
 Raw registry of `DomComponentRenderer` functions keyed by element type.
 

package/api/@xmachines/play-dom-demo/README.md

@@ -0,0 +1,145 @@
+[Documentation](../../README.md) / @xmachines/play-dom-demo
+
+# Vanilla DOM Demo
+
+Vanilla DOM renderer demo for `@xmachines/play-dom` — actor + `connectRenderer` without a router.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `connectRenderer` wiring `PlayRenderer`-equivalent DOM rendering without a framework
+- Auth machine states (home → login → dashboard) drive DOM updates via TC39 Signal watchers
+- `watchSignal` for reactive nav visibility and debug panel updates
+- Non-browser invariant tests plus browser renderer coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-dom-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` calls `definePlayer({ machine: authMachine })` and starts the actor.
+2. `initShell(actor, app)` from `src/shell.ts` builds the HTML scaffold and registers all event listeners.
+3. `makeComponents(actor)` constructs a `DomRegistry` of stateless and stateful `DomComponentRenderer` functions.
+4. `connectRenderer({ actor, registry, container })` wires the registry to the actor — view switches happen automatically when actor state changes.
+5. `watchSignal(actor.state, ...)` drives nav login/logout button visibility and the debug panel.
+6. Browser tests in `test/browser/` validate startup rendering and auth interactions.
+
+```ts
+// src/main.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const app = document.getElementById("app");
+if (app) {
+	initShell(actor, app);
+}
+```
+
+```ts
+// src/shell.ts (shape)
+const disconnectRenderer = connectRenderer({
+	actor,
+	registry,
+	container: viewContent,
+});
+
+const unwatchState = watchSignal(actor.state, () => {
+	const snapshot = actor.getSnapshot();
+	navLogin.hidden = snapshot.context.isAuthenticated;
+	navLogout.hidden = !snapshot.context.isAuthenticated;
+});
+```
+
+```ts
+// src/shell.ts — sending events (shape)
+actor.send({ type: "play.route", to: "#login" });
+actor.send({ type: "auth.login", username });
+actor.send({ type: "auth.logout" });
+```
+
+## Key Files
+
+- `src/main.ts` - actor creation and shell bootstrap
+- `src/shell.ts` - DOM scaffold, `DomRegistry` construction, `connectRenderer` wiring, and `watchSignal` for reactive nav and debug panel
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** Navigation buttons dispatch `play.route` events to the actor. The actor evaluates guards and transitions to the correct state — the DOM never decides which view to show.
+2. **Passive Infrastructure:** `connectRenderer` and `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
+3. **Signal-Only Reactivity:** `watchSignal` (from `@xmachines/play-signals`) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and project DOM state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: both `disconnectRenderer()` and `unwatchState()` must be called to avoid memory leaks. In this demo, cleanup is returned from `initShell` and called on `beforeunload`.
+
+## Adapter Boundaries
+
+`connectRenderer` (from `@xmachines/play-dom`) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                            | Description                      |
+| -------------------------------------------------- | -------------------------------- |
+| `npm run dev -w @xmachines/play-dom-demo`          | Start Vite dev server            |
+| `npm run build -w @xmachines/play-dom-demo`        | Build production bundle          |
+| `npm run preview -w @xmachines/play-dom-demo`      | Preview built bundle             |
+| `npm run test -w @xmachines/play-dom-demo`         | Run Vitest test suite            |
+| `npm run test:browser -w @xmachines/play-dom-demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+npm run test -w @xmachines/play-dom-demo
+npm run test:browser -w @xmachines/play-dom-demo
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Play DOM package README](../play-dom/README.md)
+- [Play DOM Router demo README](../play-dom-router-demo/README.md)
+
+## Variables
+
+- [About](variables/About.md)
+- [Contact](variables/Contact.md)
+- [Dashboard](variables/Dashboard.md)
+- [Home](variables/Home.md)
+- [Login](variables/Login.md)
+- [Navigation](variables/Navigation.md)
+- [Overview](variables/Overview.md)
+- [Profile](variables/Profile.md)
+- [Settings](variables/Settings.md)
+- [Stats](variables/Stats.md)
+
+## Functions
+
+- [initShell](functions/initShell.md)

package/api/@xmachines/play-dom-demo/functions/initShell.md

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / initShell
+
+# Function: initShell()
+
+```ts
+function initShell(actor, appElement): () => void;
+```
+
+Defined in: [shell.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/shell.ts#L32)
+
+## Parameters
+
+| Parameter    | Type                                                             |
+| ------------ | ---------------------------------------------------------------- |
+| `actor`      | [`AuthActor`](../../play-actor-shared/type-aliases/AuthActor.md) |
+| `appElement` | `HTMLElement`                                                    |
+
+## Returns
+
+() => `void`

package/api/@xmachines/play-dom-demo/variables/About.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / About
+
+# Variable: About
+
+```ts
+const About: ComponentFn<AuthCatalog, "About">;
+```
+
+Defined in: [components/About.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/About.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Contact.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Contact
+
+# Variable: Contact
+
+```ts
+const Contact: ComponentFn<AuthCatalog, "Contact">;
+```
+
+Defined in: [components/Contact.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Contact.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Dashboard.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Dashboard
+
+# Variable: Dashboard
+
+```ts
+const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
+```
+
+Defined in: [components/Dashboard.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Dashboard.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Home.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Home
+
+# Variable: Home
+
+```ts
+const Home: ComponentFn<AuthCatalog, "Home">;
+```
+
+Defined in: [components/Home.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Home.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Login.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Login
+
+# Variable: Login
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login">;
+```
+
+Defined in: [components/Login.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Login.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Navigation.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Navigation
+
+# Variable: Navigation
+
+```ts
+const Navigation: ComponentFn<AuthCatalog, "Navigation">;
+```
+
+Defined in: [components/Navigation.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Navigation.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Overview.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Overview
+
+# Variable: Overview
+
+```ts
+const Overview: ComponentFn<AuthCatalog, "Overview">;
+```
+
+Defined in: [components/Overview.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Overview.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Profile.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Profile
+
+# Variable: Profile
+
+```ts
+const Profile: ComponentFn<AuthCatalog, "Profile">;
+```
+
+Defined in: [components/Profile.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Profile.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Settings.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Settings
+
+# Variable: Settings
+
+```ts
+const Settings: ComponentFn<AuthCatalog, "Settings">;
+```
+
+Defined in: [components/Settings.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Settings.ts#L4)

package/api/@xmachines/play-dom-demo/variables/Stats.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Stats
+
+# Variable: Stats
+
+```ts
+const Stats: ComponentFn<AuthCatalog, "Stats">;
+```
+
+Defined in: [components/Stats.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/examples/demo/src/components/Stats.ts#L4)

package/api/@xmachines/play-dom-router/functions/connectRouter.md

@@ -6,7 +6,7 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom-router/src/connect-router.ts#L48)
+Defined in: [play-dom-router/src/connect-router.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/connect-router.ts#L48)
 
 Connect vanilla router to actor (pure browser integration).
 

package/api/@xmachines/play-dom-router/functions/createBrowserHistory.md

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom-router/src/create-browser-history.ts#L120)
+Defined in: [play-dom-router/src/create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-browser-history.ts#L120)
 
 Create browser history that wraps window.history
 

package/api/@xmachines/play-dom-router/functions/createRouteMap.md

@@ -6,7 +6,7 @@
 function createRouteMap(machine): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map-from-machine.ts#L26)
+Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-router/src/create-route-map-from-machine.ts#L26)
 
 Create a `BaseRouteMap` from an XState state machine.
 

package/api/@xmachines/play-dom-router/functions/createRouter.md

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-dom-router/src/create-router.ts#L52)
+Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom-router/src/create-router.ts#L52)
 
 Create vanilla router for framework-agnostic routing.