@xmachines/docs 1.0.0-beta.29 → 1.0.0-beta.31

package/api/@xmachines/play/classes/PlayError.md

@@ -2,7 +2,7 @@
 
 # Class: PlayError
 
-Defined in: [packages/play/src/errors.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play/src/errors.ts#L63)
+Defined in: [packages/play/src/errors.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play/src/errors.ts#L63)
 
 Base class for all typed runtime errors thrown by `@xmachines/*` packages.
 
@@ -82,7 +82,7 @@ new PlayError(
    options?): PlayError;
 ```
 
-Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play/src/errors.ts#L82)
+Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play/src/errors.ts#L82)
 
 #### Parameters
 
@@ -108,10 +108,10 @@ Error.constructor;
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from          | Defined in                                                                                                                         |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.cause`           | -                                                                                                                                  |
-| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play/src/errors.ts#L74) |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play/src/errors.ts#L74) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.message`         | -                                                                                                                                  |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.name`            | -                                                                                                                                  |
-| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play/src/errors.ts#L65) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play/src/errors.ts#L65) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.stack`           | -                                                                                                                                  |
 | <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | -                                                                                                                                  |
 

package/api/@xmachines/play/type-aliases/PlayEvent.md

@@ -6,7 +6,7 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play/src/types.ts#L69)
+Defined in: [packages/play/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play/src/types.ts#L69)
 
 Generic event type for Play Architecture
 
@@ -34,7 +34,7 @@ Robot, and other state machine libraries.
 
 | Name   | Type     | Defined in                                                                                                                       |
 | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play/src/types.ts#L70) |
+| `type` | `string` | [packages/play/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play/src/types.ts#L70) |
 
 ## Type Parameters
 

package/api/@xmachines/play-actor/classes/AbstractActor.md

@@ -2,7 +2,7 @@
 
 # Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L141)
+Defined in: [packages/play-actor/src/abstract-actor.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L141)
 
 Abstract base class for Play Architecture actors.
 
@@ -67,7 +67,7 @@ Actor<TLogic>.constructor
 | <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                       | `Actor.ref`       | -                                                                                                                                                                |
 | <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                     | `Actor.sessionId` | -                                                                                                                                                                |
 | <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                       | `Actor.src`       | -                                                                                                                                                                |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation. | -                 | [packages/play-actor/src/abstract-actor.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L151) |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | Reactive snapshot of current actor state. Infrastructure observes this signal to react to state changes without directly coupling to the actor's internal state machine implementation. | -                 | [packages/play-actor/src/abstract-actor.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L151) |
 | <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                 | `Actor.system`    | -                                                                                                                                                                |
 | <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                       | `Actor.systemId`  | -                                                                                                                                                                |
 
@@ -238,7 +238,7 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L158)
+Defined in: [packages/play-actor/src/abstract-actor.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L158)
 
 Send event to Actor.
 

package/api/@xmachines/play-actor/functions/typedSpec.md

@@ -6,7 +6,7 @@
 function typedSpec<TContext>(spec): PlaySpec;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L86)
+Defined in: [packages/play-actor/src/abstract-actor.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L86)
 
 Identity helper that constrains a `PlaySpec` object's `contextProps` to keys
 of a specific machine context type, giving compile-time validation and IDE

package/api/@xmachines/play-actor/interfaces/PlaySpec.md

@@ -2,7 +2,7 @@
 
 # Interface: PlaySpec
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L43)
+Defined in: [packages/play-actor/src/abstract-actor.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L43)
 
 XMachines extension of `@json-render/core` `Spec`.
 
@@ -22,7 +22,7 @@ entries against your machine's context type at compile time.
 
 | Property                                           | Modifier   | Type                              | Description                                                                                                                                                                                                                                                                                             | Inherited from  | Defined in                                                                                                                                                     |
 | -------------------------------------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-contextprops"></a> `contextProps?` | `readonly` | readonly `string`[]               | Explicit allowlist of machine context field names to expose as prop slots. Each named field is merged into every spec element's `props` at view derivation time, filling any slot whose current value is `undefined`. Use `typedSpec<TContext>(...)` to constrain entries to `keyof TContext & string`. | -               | [packages/play-actor/src/abstract-actor.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L51) |
+| <a id="property-contextprops"></a> `contextProps?` | `readonly` | readonly `string`[]               | Explicit allowlist of machine context field names to expose as prop slots. Each named field is merged into every spec element's `props` at view derivation time, filling any slot whose current value is `undefined`. Use `typedSpec<TContext>(...)` to constrain entries to `keyof TContext & string`. | -               | [packages/play-actor/src/abstract-actor.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L51) |
 | <a id="property-elements"></a> `elements`          | `public`   | `Record`\<`string`, `UIElement`\> | Flat map of elements by key                                                                                                                                                                                                                                                                             | `Spec.elements` | -                                                                                                                                                              |
 | <a id="property-root"></a> `root`                  | `public`   | `string`                          | Root element key                                                                                                                                                                                                                                                                                        | `Spec.root`     | -                                                                                                                                                              |
 | <a id="property-state"></a> `state?`               | `public`   | `Record`\<`string`, `unknown`\>   | Optional initial state to seed the state model. Components using statePath will read from / write to this state.                                                                                                                                                                                        | `Spec.state`    | -                                                                                                                                                              |

package/api/@xmachines/play-actor/interfaces/Routable.md

@@ -2,7 +2,7 @@
 
 # Interface: Routable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L27)
+Defined in: [packages/play-actor/src/abstract-actor.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L27)
 
 Optional capability: Routing support
 
@@ -10,5 +10,5 @@ Optional capability: Routing support
 
 | Property                                          | Modifier   | Type                                                                                         | Defined in                                                                                                                                                     |
 | ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [packages/play-actor/src/abstract-actor.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L28) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L29) |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [packages/play-actor/src/abstract-actor.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L28) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L29) |

package/api/@xmachines/play-actor/interfaces/ViewMetadata.md

@@ -2,7 +2,7 @@
 
 # Interface: ViewMetadata
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L100)
+Defined in: [packages/play-actor/src/abstract-actor.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L100)
 
 View metadata for rendering.
 
@@ -13,5 +13,5 @@ Used by PlayRenderer to dynamically render UI based on actor state.
 
 | Property                                    | Type                      | Description                                                                                                                                                                                                                                | Defined in                                                                                                                                                       |
 | ------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-component"></a> `component` | `string`                  | Root element type name (for diagnostics and component resolution)                                                                                                                                                                          | [packages/play-actor/src/abstract-actor.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L102) |
-| <a id="property-spec"></a> `spec`           | [`PlaySpec`](PlaySpec.md) | XMachines view spec — extends `@json-render/core` Spec with `contextProps` for explicit context field exposure. Use `typedSpec<TContext>(...)` at the definition site to validate `contextProps` entries against the machine context type. | [packages/play-actor/src/abstract-actor.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L110) |
+| <a id="property-component"></a> `component` | `string`                  | Root element type name (for diagnostics and component resolution)                                                                                                                                                                          | [packages/play-actor/src/abstract-actor.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L102) |
+| <a id="property-spec"></a> `spec`           | [`PlaySpec`](PlaySpec.md) | XMachines view spec — extends `@json-render/core` Spec with `contextProps` for explicit context field exposure. Use `typedSpec<TContext>(...)` at the definition site to validate `contextProps` entries against the machine context type. | [packages/play-actor/src/abstract-actor.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L110) |

package/api/@xmachines/play-actor/interfaces/Viewable.md

@@ -2,7 +2,7 @@
 
 # Interface: Viewable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L121)
+Defined in: [packages/play-actor/src/abstract-actor.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L121)
 
 Actor capability for exposing renderable view state.
 
@@ -15,4 +15,4 @@ framework adapter.
 
 | Property                                        | Modifier   | Type                                                                                                            | Description                                                                                                                                        | Defined in                                                                                                                                                       |
 | ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentview"></a> `currentView` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`ViewMetadata`](ViewMetadata.md) \| `null`\> | Current view signal. State signal containing view.component and view.spec from meta.view. Infrastructure renders view — Logic-Driven UI invariant. | [packages/play-actor/src/abstract-actor.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-actor/src/abstract-actor.ts#L128) |
+| <a id="property-currentview"></a> `currentView` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`ViewMetadata`](ViewMetadata.md) \| `null`\> | Current view signal. State signal containing view.component and view.spec from meta.view. Infrastructure renders view — Logic-Driven UI invariant. | [packages/play-actor/src/abstract-actor.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-actor/src/abstract-actor.ts#L128) |

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

@@ -14,38 +14,61 @@ npm install @xmachines/play-dom
 
 ## Key Exports
 
-- `connectRenderer({ actor, registry, container })` — connect actor view signal to DOM
-- `defineRegistry(catalog, { components, actions })` — build a catalog-typed `DomRegistry`
+- `connectRenderer({ actor, registry, container, handlers })` — connect actor view signal to DOM
+- `defineRegistry(catalog, { components, actions })` — build a catalog-typed `DomRegistry` with real async action handlers
+- `schema` — DOM schema for use with `defineCatalog` (mirrors `@json-render/react/schema` shape)
 - `PlayRenderer` — class-based renderer (connect/disconnect lifecycle)
 - `ComponentFn<C, K>` — catalog-typed DOM component function type
 - `ComponentContext<C, K>` — context passed to each `ComponentFn` (props, emit, on, children, bindings)
-- `renderSpec(spec, store, registry, send, actorActions)` — pure Spec → DOM renderer
+- `renderSpec(spec, store, registry, send, handlers)` — pure Spec → DOM renderer
 
 ## Usage
 
 ```ts
 import { definePlayer } from "@xmachines/play-xstate";
-import { connectRenderer, defineRegistry } from "@xmachines/play-dom";
-import { authMachine, authCatalog, type AuthCatalog } from "@xmachines/play-actor-shared";
+import { connectRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { authCatalogDef, type AuthActor } from "@xmachines/play-actor-shared";
 import type { ComponentFn } from "@xmachines/play-dom";
 
+// 1. Build catalog with DOM schema
+const authCatalog = defineCatalog(schema, authCatalogDef);
+type AuthCatalog = typeof authCatalog;
+
+// 2. Implement catalog components
 const Home: ComponentFn<AuthCatalog, "Home"> = ({ props }) => {
 	const el = document.createElement("section");
 	el.textContent = props.title;
 	return el;
 };
 
-const { registry } = defineRegistry(authCatalog, {
+// 3. Build registry with real async action handlers
+const registryResult = defineRegistry(authCatalog, {
 	components: { Home /* ... */ },
-	actions: { login: "auth.login", logout: "auth.logout" },
+	actions: {
+		login: async (params) => {
+			if (!params) return;
+			actor.send({ type: "auth.login", username: params.username });
+		},
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
 });
 
-const createPlayer = definePlayer({ machine: authMachine });
-const actor = createPlayer();
+// 4. Resolve handlers and connect
+const actor = definePlayer({ machine: authMachine })();
 actor.start();
 
+const handlers = registryResult.handlers(
+	() => undefined,
+	() => ({}),
+);
 const container = document.getElementById("app")!;
-const disconnect = connectRenderer({ actor, registry, container });
+const disconnect = connectRenderer({
+	actor,
+	registry: registryResult.registry,
+	container,
+	handlers,
+});
 ```
 
 ## Learn More
@@ -90,10 +113,17 @@ Public API split into two layers:
 
 ## Type Aliases
 
+- [ActionFn](type-aliases/ActionFn.md)
+- [Actions](type-aliases/Actions.md)
 - [ComponentFn](type-aliases/ComponentFn.md)
 - [ComponentRegistry](type-aliases/ComponentRegistry.md)
 - [DomComponentRenderer](type-aliases/DomComponentRenderer.md)
 - [DomRegistry](type-aliases/DomRegistry.md)
+- [DomSchema](type-aliases/DomSchema.md)
+
+## Variables
+
+- [schema](variables/schema.md)
 
 ## Functions
 

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

@@ -2,21 +2,29 @@
 
 # Class: PlayRenderer
 
-Defined in: [PlayRenderer.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/src/PlayRenderer.ts#L40)
+Defined in: [PlayRenderer.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/PlayRenderer.ts#L42)
 
 PlayRenderer connects an actor's currentView signal to the DOM renderer.
 
 Usage:
 
 ```typescript
-const renderer = new PlayRenderer(container, actor, registry, { actions: { ... } });
+const { registry, handlers } = defineRegistry(catalog, { components, actions });
+const resolvedHandlers = handlers(
+	() => undefined,
+	() => ({}),
+);
+const renderer = new PlayRenderer(container, actor, registry, { handlers: resolvedHandlers });
 renderer.connect();
 
 // Controlled mode — bring your own store:
 import { createAtom } from "@xstate/store";
 import { xstateStoreStateStore } from "@json-render/xstate";
 const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
-const renderer = new PlayRenderer(container, actor, registry, { store, actions: { ... } });
+const renderer = new PlayRenderer(container, actor, registry, {
+	store,
+	handlers: resolvedHandlers,
+});
 
 // Later:
 renderer.disconnect();
@@ -34,16 +42,16 @@ new PlayRenderer(
    options?): PlayRenderer;
 ```
 
-Defined in: [PlayRenderer.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/src/PlayRenderer.ts#L52)
+Defined in: [PlayRenderer.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/PlayRenderer.ts#L54)
 
 #### Parameters
 
-| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                   |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | The `HTMLElement` to render into. Cleared and repopulated on every view transition.                                                                                                                                           |
-| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance providing the `currentView` signal (must implement `Viewable`).                                                                                                                                                |
-| `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Map of component type names to `DomComponentRenderer` functions.                                                                                                                                                              |
-| `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)                                                                                                                                                                                                              | Optional configuration: `actions` map (action name → XState event type) and optional external `store` (controlled mode — when omitted, a fresh `@xstate/store` atom is created per view transition seeded from `spec.state`). |
+| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | The `HTMLElement` to render into. Cleared and repopulated on every view transition.                                                                                                                                        |
+| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance providing the `currentView` signal (must implement `Viewable`).                                                                                                                                             |
+| `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Map of component type names to `DomComponentRenderer` functions.                                                                                                                                                           |
+| `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)                                                                                                                                                                                                              | Optional configuration: `handlers` map (action name → async handler) and optional external `store` (controlled mode — when omitted, a fresh `@xstate/store` atom is created per view transition seeded from `spec.state`). |
 
 #### Returns
 
@@ -57,7 +65,7 @@ Defined in: [PlayRenderer.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/bl
 connect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/src/PlayRenderer.ts#L63)
+Defined in: [PlayRenderer.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/PlayRenderer.ts#L65)
 
 Start watching actor.currentView and render to container.
 Renders the initial view synchronously, then subscribes to signal changes.
@@ -74,7 +82,7 @@ Renders the initial view synchronously, then subscribes to signal changes.
 disconnect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/src/PlayRenderer.ts#L71)
+Defined in: [PlayRenderer.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/PlayRenderer.ts#L73)
 
 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.29/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.31/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

@@ -6,25 +6,10 @@
 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.29/packages/play-dom/src/json-render/types.ts#L351)
+Defined in: [json-render/types.ts:213](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L213)
 
 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                                                                                                                       |
@@ -47,15 +32,17 @@ need to manage it separately.
 ```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, {
+const registryResult = defineRegistry(authCatalog, {
   components: { Home, Login, Dashboard, ... },
   actions: {
-    login: "auth.login",
-    logout: "auth.logout",
+    login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+    logout: async () => actor.send({ type: 'auth.logout' }),
+    route: async ({ to, params }) => actor.send({ type: 'play.route', to, params }),
   },
 });
 
-connectRenderer({ actor, registry, container, actions: actorActions });
+const { registry, handlers } = registryResult;
+const resolvedHandlers = handlers(() => undefined, () => ({}));
+connectRenderer({ actor, registry, container, handlers: resolvedHandlers });
 ```

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

@@ -3,10 +3,10 @@
 # Function: renderSpec()
 
 ```ts
-function renderSpec(spec, store, registry, send, actorActions): Node | null;
+function renderSpec(spec, store, registry, send, handlers): Node | null;
 ```
 
-Defined in: [json-render/renderer.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/packages/play-dom/src/json-render/renderer.ts#L54)
+Defined in: [json-render/renderer.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/renderer.ts#L53)
 
 Render a Spec tree into DOM nodes using the provided `DomRegistry`.
 
@@ -19,13 +19,13 @@ built by `defineRegistry` — this function only orchestrates the traversal.
 
 ## Parameters
 
-| Parameter      | Type                                            | Description                                          |
-| -------------- | ----------------------------------------------- | ---------------------------------------------------- |
-| `spec`         | `Spec`                                          | The json-render `Spec` describing the UI tree.       |
-| `store`        | `StateStore`                                    | Live `StateStore` bound to `spec.state`.             |
-| `registry`     | [`DomRegistry`](../type-aliases/DomRegistry.md) | Map of element type names → `DomComponentRenderer`.  |
-| `send`         | (`event`) => `void`                             | Dispatcher for interaction events (e.g. actor.send). |
-| `actorActions` | `Record`\<`string`, `string`\>                  | Map of catalog action names → event type strings.    |
+| Parameter  | Type                                            | Description                                                  |
+| ---------- | ----------------------------------------------- | ------------------------------------------------------------ |
+| `spec`     | `Spec`                                          | The json-render `Spec` describing the UI tree.               |
+| `store`    | `StateStore`                                    | Live `StateStore` bound to `spec.state`.                     |
+| `registry` | [`DomRegistry`](../type-aliases/DomRegistry.md) | Map of element type names → `DomComponentRenderer`.          |
+| `send`     | (`event`) => `void`                             | Dispatcher for interaction events (e.g. actor.send).         |
+| `handlers` | `Record`\<`string`, `ActionHandler`\>           | Map of catalog action names → async ActionHandler functions. |
 
 ## Returns
 
@@ -37,9 +37,11 @@ or has no registered renderer.
 ## Example
 
 ```ts
-const node = renderSpec(spec, store, registry, actor.send.bind(actor), {
-	login: "auth.login",
-	logout: "auth.logout",
-});
+const { registry, handlers } = defineRegistry(catalog, { components, actions });
+const resolvedHandlers = handlers(
+	() => undefined,
+	() => ({}),
+);
+const node = renderSpec(spec, store, registry, actor.send.bind(actor), resolvedHandlers);
 if (node) container.appendChild(node);
 ```

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

@@ -2,46 +2,7 @@
 
 # Interface: ComponentContext\<C, K\>
 
-Defined in: [json-render/types.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.29/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;
-};
-```
+Defined in: [json-render/types.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L78)
 
 ## Type Parameters
 
@@ -52,11 +13,11 @@ const Login: ComponentFn<AuthCatalog, "Login"> = ({ props, emit, on, bindings })
 
 ## 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.29/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.29/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.29/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.29/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.29/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.29/packages/play-dom/src/json-render/types.ts#L154) |
+| Property                                  | Type                                          | Description                                                                      | Defined in                                                                                                                                   |
+| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. | [json-render/types.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L88)   |
+| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list.                            | [json-render/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L84)   |
+| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                        | [json-render/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L100) |
+| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                           | [json-render/types.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L92)   |
+| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map.                 | [json-render/types.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L96)   |
+| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                          | [json-render/types.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.31/packages/play-dom/src/json-render/types.ts#L80)   |