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

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

@@ -2,7 +2,7 @@
 
 # Class: PlayRenderer
 
-Defined in: [PlayRenderer.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/PlayRenderer.ts#L39)
+Defined in: [PlayRenderer.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/PlayRenderer.ts#L40)
 
 PlayRenderer connects an actor's currentView signal to the DOM renderer.
 
@@ -34,7 +34,7 @@ new PlayRenderer(
    options?): PlayRenderer;
 ```
 
-Defined in: [PlayRenderer.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/PlayRenderer.ts#L51)
+Defined in: [PlayRenderer.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/PlayRenderer.ts#L52)
 
 #### Parameters
 
@@ -57,7 +57,7 @@ Defined in: [PlayRenderer.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/bl
 connect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/PlayRenderer.ts#L62)
+Defined in: [PlayRenderer.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/PlayRenderer.ts#L63)
 
 Start watching actor.currentView and render to container.
 Renders the initial view synchronously, then subscribes to signal changes.
@@ -74,7 +74,7 @@ Renders the initial view synchronously, then subscribes to signal changes.
 disconnect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/PlayRenderer.ts#L70)
+Defined in: [PlayRenderer.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/PlayRenderer.ts#L71)
 
 Stop watching and clear the container.
 

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

@@ -6,7 +6,7 @@
 function connectRenderer(options): () => void;
 ```
 
-Defined in: [connect-renderer.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/connect-renderer.ts#L46)
+Defined in: [connect-renderer.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/connect-renderer.ts#L46)
 
 Connect a signal-driven DOM renderer to an actor's currentView signal.
 

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

@@ -0,0 +1,61 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / defineRegistry
+
+# Function: defineRegistry()
+
+```ts
+function defineRegistry<C>(_catalog, options): DefineRegistryResult;
+```
+
+Defined in: [json-render/types.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/types.ts#L351)
+
+Build a `DomRegistry` from a catalog and component/action options.
+
+Mirrors the `defineRegistry(catalog, options)` API from @json-render/react,
+/solid, /svelte, /vue. The catalog parameter is used for TypeScript inference
+only (the same as in the framework renderers — it is not used at runtime).
+
+Each component in `options.components` is wrapped in a `DomComponentRenderer`
+adapter that:
+
+- Resolves props and two-way binding paths via `@json-render/core`
+- Builds `emit(event)` and `on(event)` closures over the element's `on` map
+- Renders child elements via `ctx.renderChildren`
+- Passes the assembled `ComponentContext` to your `ComponentFn`
+
+The `actions` map is passed through as `actorActions` so the caller does not
+need to manage it separately.
+
+## Type Parameters
+
+| Type Parameter                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------ |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\> |
+
+## Parameters
+
+| Parameter  | Type                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| `_catalog` | `C`                                                                      |
+| `options`  | [`DefineRegistryOptions`](../interfaces/DefineRegistryOptions.md)\<`C`\> |
+
+## Returns
+
+[`DefineRegistryResult`](../interfaces/DefineRegistryResult.md)
+
+## Example
+
+```ts
+import { defineRegistry } from "@xmachines/play-dom";
+import { authCatalog } from "@xmachines/play-actor-shared";
+import { Home, Login, Dashboard } from "./components/index.js";
+
+const { registry, actorActions } = defineRegistry(authCatalog, {
+  components: { Home, Login, Dashboard, ... },
+  actions: {
+    login: "auth.login",
+    logout: "auth.logout",
+  },
+});
+
+connectRenderer({ actor, registry, container, actions: actorActions });
+```

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

@@ -3,26 +3,43 @@
 # Function: renderSpec()
 
 ```ts
-function renderSpec(spec, store, registry, send, actor, actorActions): Node | null;
+function renderSpec(spec, store, registry, send, actorActions): Node | null;
 ```
 
-Defined in: [dom-renderer.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/dom-renderer.ts#L26)
+Defined in: [json-render/renderer.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.28/packages/play-dom/src/json-render/renderer.ts#L54)
 
-Render a Spec tree into DOM nodes using the provided DomRegistry.
+Render a Spec tree into DOM nodes using the provided `DomRegistry`.
+
+Traverses the spec from `spec.root`, evaluates visibility, resolves all prop
+expressions (including `$state`, `$bindState`, `$computed`, `$template`, etc.),
+and calls the matching `DomComponentRenderer` for each visible element.
+
+Event wiring and child rendering are handled inside the component wrapper
+built by `defineRegistry` — this function only orchestrates the traversal.
 
 ## Parameters
 
-| Parameter      | Type                                                                                                                                                                                                                                                             | Description                                                               |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `spec`         | `Spec`                                                                                                                                                                                                                                                           | The json-render Spec describing the UI tree                               |
-| `store`        | `StateStore`                                                                                                                                                                                                                                                     | StateStore holding the current state values                               |
-| `registry`     | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Map of element type names to DomComponentRenderer functions               |
-| `send`         | (`event`) => `void`                                                                                                                                                                                                                                              | Function to dispatch XState events from UI interactions                   |
-| `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) | Raw actor — available to DOM components for state reading, complex events |
-| `actorActions` | `Record`\<`string`, `string`\>                                                                                                                                                                                                                                   | Map of json-render action names → XState event types                      |
+| Parameter      | Type                                            | Description                                          |
+| -------------- | ----------------------------------------------- | ---------------------------------------------------- |
+| `spec`         | `Spec`                                          | The json-render `Spec` describing the UI tree.       |
+| `store`        | `StateStore`                                    | Live `StateStore` bound to `spec.state`.             |
+| `registry`     | [`DomRegistry`](../type-aliases/DomRegistry.md) | Map of element type names → `DomComponentRenderer`.  |
+| `send`         | (`event`) => `void`                             | Dispatcher for interaction events (e.g. actor.send). |
+| `actorActions` | `Record`\<`string`, `string`\>                  | Map of catalog action names → event type strings.    |
 
 ## Returns
 
 `Node` \| `null`
 
-The root DOM node, or null if root element is invisible or unknown
+The root DOM `Node`, or `null` if the root is invisible
+or has no registered renderer.
+
+## Example
+
+```ts
+const node = renderSpec(spec, store, registry, actor.send.bind(actor), {
+	login: "auth.login",
+	logout: "auth.logout",
+});
+if (node) container.appendChild(node);
+```

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

@@ -0,0 +1,62 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / ComponentContext
+
+# Interface: ComponentContext\<C, K\>
+
+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.
+
+Mirrors the `ComponentContext<C, K>` shape from @json-render/react, /solid,
+/svelte, /vue with three DOM-specific adaptations:
+
+- `children` is `Node[]` instead of a framework node/snippet/slot
+- `bindings` is `Record<string, string> | undefined` (path strings for DOM
+  consumers that implement their own two-way binding, e.g. input value ↔ store)
+- `ctx` (low-level `DomRenderContext`) is exposed for advanced use cases
+  (framework renderers do not expose this)
+
+## Example
+
+```ts
+const Login: ComponentFn<AuthCatalog, "Login"> = ({ props, emit, on, bindings }) => {
+	const section = document.createElement("section");
+
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+
+	// Two-way binding: write back to state store when input changes
+	if (bindings?.username) {
+		input.addEventListener("input", () => {
+			// bindings.username contains the store path e.g. "/username"
+		});
+	}
+
+	const btn = document.createElement("button");
+	const handle = on("submit");
+	btn.addEventListener("click", (e) => {
+		if (handle.shouldPreventDefault) e.preventDefault();
+		handle.emit();
+	});
+
+	section.append(input, btn);
+	return section;
+};
+```
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Properties
+
+| Property                                  | Type                                          | Description                                                                                                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                   |
+| ----------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. 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,17 +2,17 @@
 
 # Interface: ConnectRendererOptions
 
-Defined in: [types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L63)
+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.
 
 ## Properties
 
-| Property                                    | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                   | Defined in                                                                                                         |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actions"></a> `actions?`    | `Record`\<`string`, `string`\>                                                                                                                                                                                                                                   | Map of json-render actionName → XState event type                                                                                                                                                                                                             | [types.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L77) |
-| <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)                                                                                                                                                                                         | [types.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L65) |
-| <a id="property-container"></a> `container` | `HTMLElement`                                                                                                                                                                                                                                                    | Container element to render into                                                                                                                                                                                                                              | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L71) |
-| <a id="property-fallback"></a> `fallback?`  | `HTMLElement` \| `null`                                                                                                                                                                                                                                          | Optional element shown when currentView is null (defaults to nothing — clears container)                                                                                                                                                                      | [types.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L74) |
-| <a id="property-registry"></a> `registry`   | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Registry of component renderers — replaces old `components` map                                                                                                                                                                                               | [types.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L68) |
-| <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. | [types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L84) |
+| 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.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

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / DefineRegistryOptions
+
+# Interface: DefineRegistryOptions\<C\>
+
+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`.
+
+Mirrors `DefineRegistryOptions<C>` from @json-render/react, /solid, /svelte, /vue
+with one intentional difference: `actions` is a `Record<string, string>` event-type
+map rather than async handler functions, because the DOM renderer dispatches events
+directly via `send()` to an XState actor instead of calling framework action handlers.
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |
+
+## Properties
+
+| 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.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

@@ -0,0 +1,18 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / DefineRegistryResult
+
+# Interface: DefineRegistryResult
+
+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`.
+
+Mirrors the `{ registry }` field from @json-render/react, /solid, /svelte, /vue.
+The DOM result also exposes `actorActions` — the resolved event-type map — so
+callers can pass it directly to `connectRenderer` or `PlayRenderer`.
+
+## Properties
+
+| 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.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,17 +2,20 @@
 
 # Interface: DomRenderContext
 
-Defined in: [types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L14)
+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)
 
-Context passed to each DomComponentRenderer when rendering an element.
+Low-level render context passed to each `DomComponentRenderer`.
+
+This is the raw renderer-level interface. Most component authors should use
+the higher-level `ComponentContext<C, K>` provided by `defineRegistry`.
 
 ## Properties
 
-| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                            | Defined in                                                                                                         |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Raw actor — access from any DOM component for state reading, complex events, lifecycle | [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L22) |
-| <a id="property-actoractions"></a> `actorActions`     | `Record`\<`string`, `string`\>                                                                                                                                                                                                                                   | Map of json-render action names → XState event types                                   | [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L24) |
-| <a id="property-renderchildren"></a> `renderChildren` | (`keys`) => `Node`[]                                                                                                                                                                                                                                             | Recursively render child elements by key                                               | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L26) |
-| <a id="property-send"></a> `send`                     | (`event`) => `void`                                                                                                                                                                                                                                              | Send an event to the actor                                                             | [types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L20) |
-| <a id="property-spec"></a> `spec`                     | `Spec`                                                                                                                                                                                                                                                           | Full spec tree                                                                         | [types.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L16) |
-| <a id="property-store"></a> `store`                   | `StateStore`                                                                                                                                                                                                                                                     | State store bound to spec.state                                                        | [types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L18) |
+| 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.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

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / EventHandle
+
+# Interface: EventHandle
+
+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)`.
+
+Matches the `EventHandle` interface from @json-render/react, /solid, /svelte, /vue.
+
+## Example
+
+```ts
+const handle = on("submit");
+if (handle.bound) {
+	btn.addEventListener("click", (e) => {
+		if (handle.shouldPreventDefault) e.preventDefault();
+		handle.emit();
+	});
+}
+```
+
+## Properties
+
+| Property                                                          | Type         | Description                                                                                                                  | Defined in                                                                                                                                 |
+| ----------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-bound"></a> `bound`                               | `boolean`    | `true` if an `on` binding exists for this event name; `false` otherwise.                                                     | [json-render/types.ts: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,13 +2,13 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L46)
+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.
 
 ## Properties
 
-| Property                                 | Type                           | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                         |
-| ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actions"></a> `actions?` | `Record`\<`string`, `string`\> | Map of json-render actionName → XState event type                                                                                                                                                                                                                                                                                                                   | [types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L48) |
-| <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. | [types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L57) |
+| 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.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

@@ -0,0 +1,53 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / ComponentFn
+
+# Type Alias: ComponentFn\<C, K\>
+
+```ts
+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.28/packages/play-dom/src/json-render/types.ts#L238)
+
+Catalog-typed DOM component function.
+
+The DOM equivalent of `ComponentFn<C, K>` from @json-render/react, /solid,
+/svelte, /vue. The only structural difference is the return type:
+`HTMLElement | Text | null` instead of a framework node.
+
+Pass implementations to `defineRegistry` — do not call directly.
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Parameters
+
+| Parameter | Type                                                                |
+| --------- | ------------------------------------------------------------------- |
+| `ctx`     | [`ComponentContext`](../interfaces/ComponentContext.md)\<`C`, `K`\> |
+
+## Returns
+
+`HTMLElement` \| `Text` \| `null`
+
+## Example
+
+```ts
+import type { ComponentFn } from "@xmachines/play-dom";
+import type { AuthCatalog } from "@xmachines/play-actor-shared";
+
+export const Home: ComponentFn<AuthCatalog, "Home"> = ({ props, children }) => {
+	const section = document.createElement("section");
+	section.setAttribute("data-page", "home");
+
+	const h2 = document.createElement("h2");
+	h2.textContent = props.title;
+	section.appendChild(h2);
+
+	children.forEach((child) => section.appendChild(child));
+	return section;
+};
+```

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

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / ComponentRegistry
+
+# Type Alias: ComponentRegistry\<C\>
+
+```ts
+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.28/packages/play-dom/src/json-render/types.ts#L251)
+
+Catalog-keyed map of `ComponentFn` implementations.
+
+Used as the `components` field in `DefineRegistryOptions`.
+TypeScript enforces that every component key declared in the catalog has
+a matching implementation.
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |

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

@@ -6,10 +6,13 @@
 type DomComponentRenderer = (element, ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L33)
+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)
 
-Pure DOM component renderer — receives a UIElement + context and returns a DOM node.
-No framework required. Return null for unknown/unsupported elements.
+Raw DOM component renderer function.
+
+Receives a resolved `UIElement` and a `DomRenderContext`, and returns a DOM
+node or `null`. Prefer using `ComponentFn<C, K>` via `defineRegistry` for
+catalog-typed, framework-consistent components.
 
 ## Parameters
 
@@ -21,3 +24,13 @@ No framework required. Return null for unknown/unsupported elements.
 ## Returns
 
 `HTMLElement` \| `Text` \| `null`
+
+## Example
+
+```ts
+const myRenderer: DomComponentRenderer = (element, ctx) => {
+	const el = document.createElement("div");
+	el.textContent = String(element.props.title ?? "");
+	return el;
+};
+```

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

@@ -6,6 +6,9 @@
 type DomRegistry = Record<string, DomComponentRenderer>;
 ```
 
-Defined in: [types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-dom/src/types.ts#L41)
+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)
 
-Registry of component renderers keyed by element type.
+Raw registry of `DomComponentRenderer` functions keyed by element type.
+
+Passed to `connectRenderer` or `PlayRenderer`. Build with `defineRegistry`
+to get catalog-typed component functions automatically wrapped.