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

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

@@ -2,13 +2,15 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [xm-types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L18)
+Defined in: [xm-types.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L18)
 
 Options for PlayRenderer.
 
 ## Properties
 
-| Property                                   | Type                                  | Description                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                               |
-| ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-handlers"></a> `handlers?` | `Record`\<`string`, `ActionHandler`\> | Map of catalog action name → async ActionHandler function. Replaces the old `actions: Record<string, string>` string-map approach.                                                                                                                                                                                                                                  | [xm-types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L23) |
-| <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:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/xm-types.ts#L32) |
+| Property                                               | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-handlers"></a> `handlers?`             | `Record`\<`string`, `ActionHandler`\>             | Pre-resolved handler map — for backward compatibility or advanced use cases. When `registryResult` is provided, this is ignored. If you need actions to receive `setState` and `state`, use `registryResult` instead.                                                                                                                                                                                     | [xm-types.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L36) |
+| <a id="property-loading"></a> `loading?`               | `boolean`                                         | When true, indicates the spec is still streaming (e.g. from an AI provider). Forwarded to renderSpec so ComponentFn implementations can read ctx.ctx.loading to show skeleton states. Also suppresses missing-child warnings during stream ingestion. Mirrors the `loading` prop from framework renderer providers.                                                                                       | [xm-types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L53) |
+| <a id="property-registryresult"></a> `registryResult?` | [`DefineRegistryResult`](DefineRegistryResult.md) | The result from `defineRegistry` — provides both the registry and the handlers factory. When provided, `PlayRenderer` wires `setState` and `getState` from the @xstate/store-backed `StateStore` into the handlers factory automatically. This is the preferred approach as it ensures actions always receive live `setState` and `state` bound to the current store. Mutually exclusive with `handlers`. | [xm-types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L28) |
+| <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:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/xm-types.ts#L45) |

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

@@ -3,14 +3,18 @@
 # Type Alias: ActionFn\<C, K\>
 
 ```ts
-type ActionFn<C, K> = (params) => Promise<void>;
+type ActionFn<C, K> = (params, setState, state) => Promise<void>;
 ```
 
-Defined in: [json-render/types.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L126)
+Defined in: [json-render/types.ts:232](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L232)
 
 Catalog-typed action function — mirrors `ActionFn<C, K>` from @json-render/react, /solid, /vue.
-`params` is typed to the exact param schema defined in the catalog, or `undefined` if no spec
-provided params. The handler must guard against undefined before accessing params.
+
+- `params` is typed to the exact param schema defined in the catalog, or `undefined` if the
+  spec provided no params. Guard against undefined before accessing params.
+- `setState` writes to the @xstate/store-backed local state store. Use it to update ephemeral
+  UI state (e.g. form field values, error messages) from within an action handler.
+- `state` is a snapshot of the current state model at the time the action was invoked.
 
 ## Type Parameters
 
@@ -21,10 +25,22 @@ provided params. The handler must guard against undefined before accessing param
 
 ## Parameters
 
-| Parameter | Type                                           |
-| --------- | ---------------------------------------------- |
-| `params`  | `InferActionParams`\<`C`, `K`\> \| `undefined` |
+| Parameter  | Type                                           |
+| ---------- | ---------------------------------------------- |
+| `params`   | `InferActionParams`\<`C`, `K`\> \| `undefined` |
+| `setState` | [`SetState`](SetState.md)                      |
+| `state`    | `StateModel`                                   |
 
 ## Returns
 
 `Promise`\<`void`\>
+
+## Example
+
+```ts
+login: async (params, setState, state) => {
+	if (!params) return;
+	setState((prev) => ({ ...prev, loading: true }));
+	await actor.send({ type: "auth.login", username: params.username });
+};
+```

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

@@ -6,7 +6,7 @@
 type Actions<C> = { [K in keyof InferCatalogActions<C>]: ActionFn<C, K> };
 ```
 
-Defined in: [json-render/types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L134)
+Defined in: [json-render/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L242)
 
 Map of catalog-typed action handler functions.
 Each key is a catalog action name; each value is an `ActionFn<C, K>` for that action.

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

@@ -0,0 +1,114 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / BaseComponentProps
+
+# Type Alias: BaseComponentProps\<P\>
+
+```ts
+type BaseComponentProps<P> = object;
+```
+
+Defined in: [json-render/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L187)
+
+Catalog-agnostic component props type.
+
+Use this when building shared component libraries that should not be tied to
+a specific catalog instance. Mirrors `BaseComponentProps<P>` from
+@json-render/react, /vue, /svelte.
+
+## Example
+
+```ts
+import type { BaseComponentProps } from "@xmachines/play-dom";
+
+function MyButton({ props, emit }: BaseComponentProps<{ label: string }>) {
+	const el = document.createElement("button");
+	el.textContent = props.label;
+	el.addEventListener("click", () => emit("click"));
+	return el;
+}
+```
+
+## Type Parameters
+
+| Type Parameter                                | Default type                    |
+| --------------------------------------------- | ------------------------------- |
+| `P` _extends_ `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> |
+
+## Properties
+
+### bindings
+
+```ts
+bindings: Record<string, string> | undefined;
+```
+
+Defined in: [json-render/types.ts:190](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L190)
+
+---
+
+### children
+
+```ts
+children: Node[];
+```
+
+Defined in: [json-render/types.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L189)
+
+---
+
+### ctx
+
+```ts
+ctx: DomRenderContext;
+```
+
+Defined in: [json-render/types.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L193)
+
+---
+
+### emit
+
+```ts
+emit: (event) => void;
+```
+
+Defined in: [json-render/types.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L191)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `string` |
+
+#### Returns
+
+`void`
+
+---
+
+### on
+
+```ts
+on: (event) => EventHandle;
+```
+
+Defined in: [json-render/types.ts:192](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L192)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `string` |
+
+#### Returns
+
+[`EventHandle`](../interfaces/EventHandle.md)
+
+---
+
+### props
+
+```ts
+props: P;
+```
+
+Defined in: [json-render/types.ts:188](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L188)

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

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / CatalogHasActions
+
+# Type Alias: CatalogHasActions\<C\>
+
+```ts
+type CatalogHasActions<C> = [InferCatalogActions<C>] extends [never]
+	? false
+	: [keyof InferCatalogActions<C>] extends [never]
+		? false
+		: true;
+```
+
+Defined in: [json-render/types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L58)
+
+Evaluates to `true` when a catalog declares at least one action; `false` otherwise.
+
+Mirrors `CatalogHasActions<C>` from @json-render/react, /solid, /vue.
+Used to make the `actions` field required in `DefineRegistryOptions` when the
+catalog defines actions, and optional when it does not.
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |

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

@@ -6,7 +6,7 @@
 type ComponentFn<C, K> = (ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [json-render/types.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L105)
+Defined in: [json-render/types.ts:198](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L198)
 
 ## Type Parameters
 

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

@@ -6,7 +6,7 @@
 type ComponentRegistry<C> = { [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K> };
 ```
 
-Defined in: [json-render/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L111)
+Defined in: [json-render/types.ts:204](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L204)
 
 ## Type Parameters
 

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

@@ -0,0 +1,39 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / DefineRegistryOptions
+
+# Type Alias: DefineRegistryOptions\<C\>
+
+```ts
+type DefineRegistryOptions<C> = object & CatalogHasActions<C> extends true ? object : object;
+```
+
+Defined in: [json-render/types.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L264)
+
+Options for `defineRegistry`.
+
+Mirrors `DefineRegistryOptions<C>` from @json-render/react, /solid, /svelte, /vue.
+`actions` accepts catalog-typed async handler functions — params, setState, and state are
+fully typed. When the catalog declares actions, `actions` is required; otherwise optional.
+
+## Type Declaration
+
+| Name          | Type                                               | Description                                                                                                                                                             | Defined in                                                                                                                                   |
+| ------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `components?` | [`ComponentRegistry`](ComponentRegistry.md)\<`C`\> | Catalog-typed component implementations. If omitted, all elements fall through to the `fallback` renderer (if provided) or return `null` — the container will be empty. | [json-render/types.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L270) |
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |
+
+## Example
+
+```ts
+actions: {
+  login: async (params, setState, state) => {
+    if (!params) return;
+    setState(prev => ({ ...prev, loading: true }));
+    actor.send({ type: 'auth.login', username: params.username });
+  },
+}
+```

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

@@ -6,7 +6,7 @@
 type DomComponentRenderer = (element, ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [json-render/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L71)
+Defined in: [json-render/types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L134)
 
 ## Parameters
 

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

@@ -6,4 +6,4 @@
 type DomRegistry = Record<string, DomComponentRenderer>;
 ```
 
-Defined in: [json-render/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L117)
+Defined in: [json-render/types.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L210)

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

@@ -6,4 +6,4 @@
 type DomSchema = typeof schema;
 ```
 
-Defined in: [json-render/schema.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/schema.ts#L60)
+Defined in: [json-render/schema.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/schema.ts#L60)

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

@@ -0,0 +1,30 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / SetState
+
+# Type Alias: SetState
+
+```ts
+type SetState = (updater) => void;
+```
+
+Defined in: [json-render/types.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/types.ts#L45)
+
+Function to update the local state store.
+
+Mirrors `SetState` from @json-render/react, /solid, /vue, /svelte.
+In the DOM renderer, this writes through to the @xstate/store-backed StateStore.
+
+## Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `updater` | (`prev`) => `Record`\<`string`, `unknown`\> |
+
+## Returns
+
+`void`
+
+## Example
+
+```ts
+setState((prev) => ({ ...prev, username: "alice" }));
+```

package/api/@xmachines/play-dom/variables/schema.md

@@ -46,7 +46,7 @@ const schema: Schema<{
 }>;
 ```
 
-Defined in: [json-render/schema.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/schema.ts#L20)
+Defined in: [json-render/schema.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-dom/src/json-render/schema.ts#L20)
 
 The schema for @xmachines/play-dom