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

package/api/@xmachines/play-xstate/interfaces/PlayerFactoryResumeOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayerFactoryResumeOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L47)
+Defined in: [packages/play-xstate/src/types.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L47)
 
 Optional restore arguments for the player factory.
 
@@ -19,4 +19,4 @@ Mirrors XState's createActor options bag while preserving the existing
 
 | Property                                   | Type                                                                              | Description                                            | Defined in                                                                                                                                     |
 | ------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-snapshot"></a> `snapshot?` | [`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\> | Persisted XState snapshot used to restore actor state. | [packages/play-xstate/src/types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L49) |
+| <a id="property-snapshot"></a> `snapshot?` | [`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\> | Persisted XState snapshot used to restore actor state. | [packages/play-xstate/src/types.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L49) |

package/api/@xmachines/play-xstate/interfaces/PlayerOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayerOptions\<TMachine\>
 
-Defined in: [packages/play-xstate/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L20)
+Defined in: [packages/play-xstate/src/types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L20)
 
 Player lifecycle hooks
 
@@ -18,8 +18,8 @@ Per CONTEXT.md: Rich set of hooks for observability
 
 | Property                                             | Type                                          | Description                      | Defined in                                                                                                                                     |
 | ---------------------------------------------------- | --------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                  | Called on actor errors           | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L38) |
-| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                           | Called when actor starts         | [packages/play-xstate/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L22) |
-| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                  | Called when state signal changes | [packages/play-xstate/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L35) |
-| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                           | Called when actor stops          | [packages/play-xstate/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L25) |
-| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition | [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L28) |
+| <a id="property-onerror"></a> `onError?`             | (`actor`, `error`) => `void`                  | Called on actor errors           | [packages/play-xstate/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L38) |
+| <a id="property-onstart"></a> `onStart?`             | (`actor`) => `void`                           | Called when actor starts         | [packages/play-xstate/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L22) |
+| <a id="property-onstatechange"></a> `onStateChange?` | (`actor`, `state`) => `void`                  | Called when state signal changes | [packages/play-xstate/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L35) |
+| <a id="property-onstop"></a> `onStop?`               | (`actor`) => `void`                           | Called when actor stops          | [packages/play-xstate/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L25) |
+| <a id="property-ontransition"></a> `onTransition?`   | (`actor`, `prevState`, `nextState`) => `void` | Called on every state transition | [packages/play-xstate/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L28) |

package/api/@xmachines/play-xstate/interfaces/RouteContext.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteContext
 
-Defined in: [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/types.ts#L19)
+Defined in: [packages/play-xstate/src/routing/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/types.ts#L19)
 
 Route build context from machine context.
 
@@ -18,7 +18,7 @@ must populate `params` explicitly.
 
 | Property                                   | Type                            | Description                                                                        | Defined in                                                                                                                                                     |
 | ------------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?` | `string`                        | Base path for relative routes                                                      | [packages/play-xstate/src/routing/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/types.ts#L21) |
-| <a id="property-hash"></a> `hash?`         | `string`                        | Hash fragment                                                                      | [packages/play-xstate/src/routing/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/types.ts#L27) |
-| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | Path-only route parameters to substitute (e.g., `:userId` from `/profile/:userId`) | [packages/play-xstate/src/routing/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/types.ts#L23) |
-| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | Query parameters                                                                   | [packages/play-xstate/src/routing/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/types.ts#L25) |
+| <a id="property-basepath"></a> `basePath?` | `string`                        | Base path for relative routes                                                      | [packages/play-xstate/src/routing/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/types.ts#L21) |
+| <a id="property-hash"></a> `hash?`         | `string`                        | Hash fragment                                                                      | [packages/play-xstate/src/routing/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/types.ts#L27) |
+| <a id="property-params"></a> `params?`     | `Record`\<`string`, `unknown`\> | Path-only route parameters to substitute (e.g., `:userId` from `/profile/:userId`) | [packages/play-xstate/src/routing/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/types.ts#L23) |
+| <a id="property-query"></a> `query?`       | `Record`\<`string`, `unknown`\> | Query parameters                                                                   | [packages/play-xstate/src/routing/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/types.ts#L25) |

package/api/@xmachines/play-xstate/type-aliases/ComposedGuard.md

@@ -6,7 +6,7 @@
 type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/guards/compose.ts#L14)
+Defined in: [packages/play-xstate/src/guards/compose.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/guards/compose.ts#L14)
 
 Narrowest public return type for guard composition helpers.
 

package/api/@xmachines/play-xstate/type-aliases/Guard.md

@@ -6,7 +6,7 @@
 type Guard<TContext, TEvent> = (args) => boolean;
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/guards/types.ts#L13)
+Defined in: [packages/play-xstate/src/guards/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/guards/types.ts#L13)
 
 Standard XState guard function signature
 

package/api/@xmachines/play-xstate/type-aliases/GuardArray.md

@@ -6,7 +6,7 @@
 type GuardArray<TContext, TEvent> = Guard<TContext, TEvent>[] | string[];
 ```
 
-Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/guards/types.ts#L23)
+Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/guards/types.ts#L23)
 
 Array of guard predicates or guard names
 

package/api/@xmachines/play-xstate/type-aliases/PlayerFactory.md

@@ -6,7 +6,7 @@
 type PlayerFactory<TMachine> = (input?, options?) => PlayerActor<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/types.ts#L57)
+Defined in: [packages/play-xstate/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/types.ts#L57)
 
 Factory function returned by definePlayer()
 

package/api/@xmachines/play-xstate/type-aliases/RouteMachineConfig.md

@@ -6,7 +6,7 @@
 type RouteMachineConfig = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L48)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L48)
 
 Minimal structural constraint for machine configs accepted by
 `formatPlayRouteTransitions`.
@@ -32,7 +32,7 @@ through the transform, so the return value remains directly usable by
 optional context?: unknown;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L49)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L49)
 
 ---
 
@@ -42,7 +42,7 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:4
 optional on?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L51)
 
 ---
 
@@ -52,4 +52,4 @@ Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:5
 optional states?: Record<string, unknown>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L50)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L50)

package/api/@xmachines/play-xstate/type-aliases/RouteStateNode.md

@@ -6,7 +6,7 @@
 type RouteStateNode = object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L13)
 
 Minimal structural shape of a single XState state node as read by
 `formatPlayRouteTransitions` when crawling the machine config.
@@ -29,7 +29,7 @@ the index signature.
 optional id?: string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L15)
 
 Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events.
 
@@ -41,7 +41,7 @@ Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` targ
 optional meta?: object;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L17)
 
 State metadata — `meta.route` marks the state as routable.
 
@@ -61,6 +61,6 @@ URL path template (e.g. `"/profile/:username"`, `"/settings/:section?"`).
 optional states?: Record<string, RouteStateNode>;
 ```
 
-Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-xstate/src/routing/format-play-route-transitions.ts#L22)
+Defined in: [packages/play-xstate/src/routing/format-play-route-transitions.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-xstate/src/routing/format-play-route-transitions.ts#L22)
 
 Nested child states, recursively crawled for additional route declarations.

package/api/@xmachines/shared/functions/defineXmVitestConfig.md

@@ -6,7 +6,7 @@
 function defineXmVitestConfig(importMetaUrl, overrides): UserConfig;
 ```
 
-Defined in: [index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/shared/src/index.ts#L10)
+Defined in: [index.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/shared/src/index.ts#L10)
 
 Create a Vitest config with XMachines workspace defaults.
 

package/api/@xmachines/shared/functions/xmAliases.md

@@ -6,7 +6,7 @@
 function xmAliases(importMetaUrl): Record<string, string>;
 ```
 
-Defined in: [index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/shared/src/index.ts#L20)
+Defined in: [index.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/shared/src/index.ts#L20)
 
 Build Vite/Vitest alias entries for all `@xmachines/*` workspace packages.
 

package/api/_media/README.md

@@ -0,0 +1,321 @@
+[Documentation](../../README.md) / @xmachines/play-dom
+
+# @xmachines/play-dom
+
+**Vanilla DOM renderer for XMachines**
+
+Framework-free view rendering driven by an XState v5 actor's `currentView` TC39 Signal. Implements the same catalog-typed `defineRegistry` / `ComponentFn` / `ActionFn` API surface as `@json-render/react`, `/solid`, `/vue`, and `/svelte`.
+
+## Installation
+
+```bash
+npm install @xmachines/play-dom @json-render/core zod
+```
+
+## Key Exports
+
+| Export                                              | Description                                                                                 |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `createRenderer(catalog, componentMap)`             | One-call factory: returns `mount(actor, container, options?) → disconnect`                  |
+| `connectRenderer(options)`                          | Functional API: connect actor → DOM with full options                                       |
+| `defineRegistry(catalog, { components, actions })`  | Build a catalog-typed `DomRegistry` with typed action handlers                              |
+| `PlayRenderer`                                      | Class-based renderer — `connect()` / `disconnect()` lifecycle                               |
+| `schema`                                            | DOM schema for `defineCatalog` (mirrors `@json-render/react/schema`)                        |
+| `ComponentFn<C, K>`                                 | Catalog-typed DOM component function type                                                   |
+| `ComponentContext<C, K>`                            | Context passed to each `ComponentFn` — `props`, `on`, `emit`, `children`, `bindings`, `ctx` |
+| `ActionFn<C, K>`                                    | `(params, setState, state) => Promise<void>` — catalog-typed action handler                 |
+| `SetState`                                          | `(updater: prev => next) => void` — write to the local state store                          |
+| `BaseComponentProps<P>`                             | Base type for catalog component prop definitions                                            |
+| `CatalogHasActions<C>`                              | Conditional type: `true` when catalog declares actions                                      |
+| `renderSpec(spec, store, registry, send, handlers)` | Pure Spec → DOM renderer (advanced use)                                                     |
+
+## Quick Start — `createRenderer`
+
+The preferred one-call pattern — mirrors all framework renderers:
+
+```typescript
+import { createRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
+import type { ComponentFn } from "@xmachines/play-dom";
+
+// 1. Define catalog
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({ title: z.string(), username: z.string().optional() }) },
+	},
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+type AppCatalog = typeof catalog;
+
+// 2. Implement components
+const Home: ComponentFn<AppCatalog, "Home"> = ({ props }) => {
+	const el = document.createElement("section");
+	el.textContent = props.title;
+	return el;
+};
+
+const Login: ComponentFn<AppCatalog, "Login"> = ({ props, on }) => {
+	const section = document.createElement("section");
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+	input.addEventListener("input", () => ctx.store.update((s) => ({ ...s, username: input.value })));
+
+	const button = document.createElement("button");
+	button.textContent = "Log In";
+	const submit = on("submit");
+	button.addEventListener("click", () => submit.emit());
+
+	section.append(input, button);
+	return section;
+};
+
+// 3. Create the renderer factory (once, at module level)
+const mount = createRenderer(catalog, { Home, Login });
+
+// 4. Mount when actor and container are ready
+const actor = createPlayer()();
+actor.start();
+
+const disconnect = mount(actor, document.getElementById("app")!);
+
+// Cleanup:
+disconnect();
+```
+
+## `defineRegistry` — Full Control
+
+When you need `registryResult.executeAction()` or want to share the registry with `connectRenderer`:
+
+```typescript
+import { defineRegistry, connectRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+	},
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+
+// Action handlers receive (params, setState, state)
+// - params: resolved from the spec's on.submit.params (e.g. { $state: "/username" })
+// - setState: write to the local state store (e.g. to clear a form)
+// - state: current local state store snapshot
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: ({ props }) => {
+			const el = document.createElement("section");
+			el.textContent = props.title;
+			return el;
+		},
+	},
+	actions: {
+		login: async (params, setState) => {
+			if (!params) return;
+			actor.send({ type: "auth.login", username: params.username });
+			setState((prev) => ({ ...prev, username: "" })); // clear the form
+		},
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+
+const disconnect = connectRenderer({
+	actor,
+	registry: registryResult.registry,
+	registryResult, // wires setState/state from xstate store automatically
+	container: document.getElementById("app")!,
+});
+```
+
+## Component API
+
+### `ComponentFn<C, K>` — component function signature
+
+```typescript
+const MyCard: ComponentFn<AppCatalog, "Card"> = ({
+	props, // catalog-typed props for this component
+	children, // Node[] — rendered child nodes
+	on, // (eventName) => EventHandle — get emit() for catalog-declared events
+	emit, // (eventName) => void — fire an event directly
+	bindings, // Record<string, string> — $bindState paths for two-way bindings
+	ctx, // DomRenderContext — store, send, handlers, loading, functions
+}) => {
+	const el = document.createElement("div");
+	el.append(...children);
+	return el;
+};
+```
+
+### Two-way binding with `$bindState`
+
+In the view spec:
+
+```json
+{ "username": { "$bindState": "/username" } }
+```
+
+In the component:
+
+```typescript
+const Login: ComponentFn<AppCatalog, "Login"> = ({ props, ctx }) => {
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+	// Write back to the store on user input
+	input.addEventListener("input", () => {
+		ctx.store.update((s) => ({ ...s, username: input.value }));
+	});
+	return input;
+};
+```
+
+### `on()` — event handle
+
+```typescript
+const submit = on("submit"); // EventHandle
+if (submit.bound) {
+	button.addEventListener("click", (e) => {
+		if (submit.shouldPreventDefault) e.preventDefault();
+		submit.emit(); // resolves params from store, calls action handler
+	});
+}
+```
+
+### `ActionFn` — action handler signature
+
+```typescript
+// Full signature — all three params are available
+login: async (params, setState, state) => {
+  actor.send({ type: "auth.login", username: params!.username });
+  setState(prev => ({ ...prev, username: "" }));
+  console.log("previous state was:", state);
+},
+
+// Params-only — setState/state can be omitted if unused
+logout: async () => actor.send({ type: "auth.logout" }),
+route: async (params) => actor.send({ type: "play.route", to: params!.to }),
+```
+
+## Spec Features
+
+`renderSpec` / `renderElement` supports these spec directives:
+
+| Directive                                              | Description                                                                           |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `visible`                                              | Boolean or `{ $state: "/path" }` — hide element when false                            |
+| `on.submit` / `on.click`                               | Action binding — `{ action: "login", params: { username: { $state: "/username" } } }` |
+| `repeat: { statePath, key? }`                          | Render children once per item in the state array at `statePath`                       |
+| `watch: { "/path": actionBinding }`                    | Fire action when store path changes after mount                                       |
+| `props.username: { $bindState: "/username" }`          | Two-way binding — read from store, write back via `ctx.store.update()`                |
+| `props.value: { $state: "/value" }`                    | Read-only store reference                                                             |
+| `props.label: { $computed: "computeFn", args: [...] }` | Computed prop via `functions` map                                                     |
+
+## `PlayRenderer` — class API
+
+```typescript
+import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+
+const { registry, registryResult } = defineRegistry(catalog, { components, actions });
+
+const renderer = new PlayRenderer(document.getElementById("app")!, actor, registry, {
+	registryResult,
+});
+
+renderer.connect(); // starts watching actor.currentView
+renderer.disconnect(); // stops watching, clears container
+
+// double-connect is safe — connect() calls disconnect() internally if already connected
+```
+
+## Options Reference
+
+### `ConnectRendererOptions` / `PlayDomOptions`
+
+| Option           | Type                            | Description                                                                   |
+| ---------------- | ------------------------------- | ----------------------------------------------------------------------------- |
+| `actor`          | `AbstractActor & Viewable`      | Actor providing `currentView` signal                                          |
+| `registry`       | `DomRegistry`                   | Component renderer map from `defineRegistry`                                  |
+| `registryResult` | `DefineRegistryResult`          | Preferred — auto-wires `setState`/`state` from xstate store                   |
+| `handlers`       | `Record<string, ActionHandler>` | Pre-resolved handlers (legacy / advanced)                                     |
+| `container`      | `HTMLElement`                   | DOM element to render into                                                    |
+| `fallback`       | `HTMLElement \| null`           | Shown on initial mount when view is `null` (initial mount only)               |
+| `store`          | `StateStore`                    | External store — controlled mode, overrides `spec.state`                      |
+| `loading`        | `boolean`                       | Streaming mode — suppresses missing-child warnings, exposes `ctx.ctx.loading` |
+
+## Learn More
+
+- [DOM Router adapter `@xmachines/play-dom-router`](../play-dom-router/README.md)
+- [API reference](../../_media/README.md)
+- [Play RFC](../../packages/docs/rfc/play.md)
+
+@xmachines/play-dom — Vanilla DOM renderer for XMachines Play architecture.
+
+Public API split into two layers:
+
+**XMachines layer** (this package):
+
+- `createRenderer()` — one-call factory: returns `mount(actor, container, options?) → disconnect`
+- `PlayRenderer` — class-based renderer with `connect()` / `disconnect()` lifecycle
+- `connectRenderer()` — functional API (backward-compat alternative to `PlayRenderer`)
+- `ConnectRendererOptions`, `PlayDomOptions`
+
+**json-render layer** (upstreamable to @json-render/dom):
+
+- `defineRegistry` — build a catalog-typed DomRegistry
+- `renderSpec` — pure Spec → DOM renderer (uses resolveElementProps from core)
+- `ComponentFn` — catalog-typed component function type
+- `ComponentContext` — catalog-typed render context (props, emit, on, children, bindings)
+- `ComponentRegistry` — catalog-typed registry input type
+- `DomComponentRenderer` — raw element-level renderer type
+- `DomRegistry` — raw registry type
+- `DomRenderContext` — raw render context
+- `EventHandle` — event handle returned by on()
+- `SetState` — state updater function passed to ActionFn
+- `CatalogHasActions` — conditional type: true when catalog declares actions
+- `BaseComponentProps` — base props type for catalog component definitions
+
+## Classes
+
+- [PlayRenderer](classes/PlayRenderer.md)
+
+## Interfaces
+
+- [ComponentContext](interfaces/ComponentContext.md)
+- [ConnectRendererOptions](interfaces/ConnectRendererOptions.md)
+- [DefineRegistryResult](interfaces/DefineRegistryResult.md)
+- [DomRenderContext](interfaces/DomRenderContext.md)
+- [EventHandle](interfaces/EventHandle.md)
+- [PlayDomOptions](interfaces/PlayDomOptions.md)
+
+## Type Aliases
+
+- [ActionFn](type-aliases/ActionFn.md)
+- [Actions](type-aliases/Actions.md)
+- [BaseComponentProps](type-aliases/BaseComponentProps.md)
+- [CatalogHasActions](type-aliases/CatalogHasActions.md)
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [ComponentRegistry](type-aliases/ComponentRegistry.md)
+- [DefineRegistryOptions](type-aliases/DefineRegistryOptions.md)
+- [DomComponentRenderer](type-aliases/DomComponentRenderer.md)
+- [DomRegistry](type-aliases/DomRegistry.md)
+- [DomSchema](type-aliases/DomSchema.md)
+- [SetState](type-aliases/SetState.md)
+
+## Variables
+
+- [schema](variables/schema.md)
+
+## Functions
+
+- [connectRenderer](functions/connectRenderer.md)
+- [createRenderer](functions/createRenderer.md)
+- [defineRegistry](functions/defineRegistry.md)
+- [renderSpec](functions/renderSpec.md)

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,7 +6,7 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/NavBar.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/examples/demo/src/components/NavBar.ts#L15)
+Defined in: [play-dom/examples/demo/src/components/NavBar.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/NavBar.ts#L15)
 
 Create and mount a reactive NavBar into the given container element.
 Returns a cleanup function to stop watching.

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

@@ -6,7 +6,7 @@
 function initShell(actor, appElement): () => void;
 ```
 
-Defined in: [play-dom/examples/demo/src/shell.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/examples/demo/src/shell.ts#L33)
+Defined in: [play-dom/examples/demo/src/shell.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/shell.ts#L35)
 
 ## Parameters
 

package/examples/@xmachines/play-dom-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/catalog.ts#L6)

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

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

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

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

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

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

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

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

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

@@ -6,4 +6,4 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Login.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/examples/demo/src/components/Login.ts#L4)
+Defined in: [play-dom/examples/demo/src/components/Login.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/Login.ts#L7)

package/examples/@xmachines/play-dom-demo/variables/NavBarView.md

@@ -6,4 +6,4 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/NavBarView.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/examples/demo/src/components/NavBarView.ts#L13)
+Defined in: [play-dom/examples/demo/src/components/NavBarView.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/examples/demo/src/components/NavBarView.ts#L13)

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

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

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

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

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

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

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

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