@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,33 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / BaseViewContextValue
+
+# Interface: BaseViewContextValue\<TRegistry\>
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L123)
+
+Framework-agnostic base for every framework's `ViewContextValue`.
+
+Holds the three fields that are identical across React, Vue, Solid, and Svelte.
+`registry` is framework-specific (each framework has its own `ComponentRegistry`
+type) so it is typed via `TRegistry` — the same generic used in `BaseActorProviderProps`.
+
+## Extended by
+
+- [`ViewContextValue`](../../play-react/interfaces/ViewContextValue.md)
+- [`ViewContextValue`](../../play-solid/interfaces/ViewContextValue.md)
+- [`ViewContextValue`](../../play-svelte/interfaces/ViewContextValue.md)
+- [`ViewContextValue`](../../play-vue/interfaces/ViewContextValue.md)
+
+## Type Parameters
+
+| Type Parameter                 | Description                                                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `TRegistry` _extends_ `object` | The framework's component registry type (e.g. `ComponentRegistry` from `@xmachines/json-render-react`). |
+
+## Properties
+
+| Property                                  | Type                                  | Description                                                                                               | Defined in                                                                                                                                               |
+| ----------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\> | Action handlers resolved against the live StateStore.                                                     | [packages/play-actor/src/abstract-actor.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L127) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                           | Component registry from registryResult.registry.                                                          | [packages/play-actor/src/abstract-actor.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L129) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](PlaySpec.md)             | The current PlaySpec to render.                                                                           | [packages/play-actor/src/abstract-actor.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L125) |
+| <a id="property-store"></a> `store`       | `StateStore`                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [packages/play-actor/src/abstract-actor.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L131) |

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

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / PlaySpec
+
+# Interface: PlaySpec
+
+Defined in: [packages/play-actor/src/abstract-actor.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L48)
+
+XMachines extension of `@xmachines/json-render-core` `Spec`.
+
+Adds `contextProps` — an explicit allowlist of machine context fields that
+`deriveCurrentView` merges into element props as low-priority slots. Only
+fields named here are ever exposed to components; nothing leaks from context
+without an opt-in declaration.
+
+Use `typedSpec<TContext>(...)` at the definition site to validate `contextProps`
+entries against your machine's context type at compile time.
+
+## Extends
+
+- `Spec`
+
+## Properties
+
+| 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:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L56) |
+| <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

@@ -1,29 +1,14 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / Routable
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / Routable
 
 # Interface: Routable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L41)
+Defined in: [packages/play-actor/src/abstract-actor.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L32)
 
 Optional capability: Routing support
 
-Actors implementing this interface can derive a route from their state.
-Router adapters observe the currentRoute signal to sync browser URLs.
-
-## Example
-
-```typescript
-class MyActor extends AbstractActor implements Routable {
-	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
-}
-
-// Router requires Routable
-function connectRouter<T extends AbstractActor & Routable>(actor: T) {
-	watcher.watch(actor.currentRoute);
-}
-```
-
 ## Properties
 
-| Property                                          | Modifier   | Type                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                          | Defined in                                                                                                                                                                               |
-| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | Current route signal Computed signal derived from state machine. Infrastructure observes to sync browser URL. Invariant: Passive Infrastructure - Infrastructure reflects route, never decides. **Example** `const watcher = new Signal.subtle.Watcher(() => { const route = actor.currentRoute.get(); console.log('Route changed:', route); }); watcher.watch(actor.currentRoute);` | [packages/play-actor/src/abstract-actor.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L58) |
+| 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:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L33) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [packages/play-actor/src/abstract-actor.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L34) |

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

@@ -1,12 +1,18 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / Viewable
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / Viewable
 
 # Interface: Viewable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L94)
+Defined in: [packages/play-actor/src/abstract-actor.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L104)
+
+Actor capability for exposing renderable view state.
+
+`Viewable` marks actors that publish a `currentView` signal.
+Renderers such as `PlayRenderer` consume this contract to resolve the
+current view description into concrete UI without embedding view logic inside the
+framework adapter.
 
 ## Properties
 
-| Property                                        | Modifier   | Type                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                     | Defined in                                                                                                                                                                                 |
-| ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-catalog"></a> `catalog`         | `readonly` | `Record`\<`string`, `unknown`\>                                                                                 | Component catalog for view resolution Maps component names to actual component implementations. Used by renderers to resolve view.component to actual UI components.                                                                                                                                                                                                            | [packages/play-actor/src/abstract-actor.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L119) |
-| <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 UI structure schema from meta.view. Infrastructure renders view. Invariant: Logic-Driven UI - View structure is defined by business logic, not JSX. **Example** `const watcher = new Signal.subtle.Watcher(() => { const view = actor.currentView.get(); console.log('View changed:', view); }); watcher.watch(actor.currentView);` | [packages/play-actor/src/abstract-actor.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-actor/src/abstract-actor.ts#L111) |
+| Property                                        | Modifier   | Type                                                                                                    | Description                                                                                                                                                                    | Defined in                                                                                                                                               |
+| ----------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentview"></a> `currentView` | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](PlaySpec.md) \| `null`\> | Current view signal. Contains the json-render PlaySpec for the current machine state, or null when no view is active. Infrastructure renders view — Logic-Driven UI invariant. | [packages/play-actor/src/abstract-actor.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-actor/src/abstract-actor.ts#L111) |

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

@@ -0,0 +1,385 @@
+[API](../../README.md) / @xmachines/play-dom
+
+# @xmachines/play-dom
+
+Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
+
+Part of the [XMachines Play monorepo](../../README.md).
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-dom
+```
+
+**Peer dependencies:**
+
+```bash
+pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render-xstate
+```
+
+## Quick Start
+
+```typescript
+import { createRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { z } from "zod";
+import type { ComponentFn } from "@xmachines/play-dom";
+
+// 1. Define a catalog
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({ title: z.string(), username: z.string().optional() }) },
+	},
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+
+// 2. Implement components
+const Home: ComponentFn<typeof catalog, "Home"> = ({ props }) => {
+	const el = document.createElement("section");
+	el.textContent = props.title;
+	return el;
+};
+
+const Login: ComponentFn<typeof catalog, "Login"> = ({ props, on }) => {
+	const el = document.createElement("section");
+	const btn = document.createElement("button");
+	const submit = on("submit");
+	btn.addEventListener("click", () => submit.emit());
+	el.append(btn);
+	return el;
+};
+
+// 3. Build the factory once (module scope)
+const mount = createRenderer(catalog, { Home, Login });
+
+// 4. Mount when actor and container are ready
+const disconnect = mount(actor, document.getElementById("app")!);
+
+// 5. Cleanup on teardown
+disconnect();
+```
+
+## Usage
+
+### `createRenderer` — one-call factory (recommended)
+
+`createRenderer` is the simplest integration path. Call it once at module scope with your catalog and component map, then call the returned `mount` function for each actor/container pair.
+
+```typescript
+import { createRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@xmachines/json-render-core";
+
+const catalog = defineCatalog(schema, {/* ... */});
+
+const mount = createRenderer(catalog, { MyComponent });
+
+const disconnect = mount(actor, document.getElementById("app")!);
+// Returns a cleanup function — call it to stop rendering and clear the container.
+disconnect();
+```
+
+### `createPlayUI` — batteries-included factory with full options
+
+Use `createPlayUI` when you need render error handling, a fallback element, navigation integration, computed functions, or custom validation — or when you need to reference `registryResult` programmatically (e.g. for `executeAction`).
+
+Factory-level options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, `fallback`) are closed over at creation time and applied on every `mount()` call. Per-mount options (`store`, `loading`) are passed to `mount()` itself.
+
+```typescript
+import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@xmachines/json-render-core";
+
+const catalog = defineCatalog(schema, {/* ... */});
+
+const registryResult = defineRegistry(catalog, {
+	components: { Home, Login },
+	actions: {
+		login: async (params, setState) => {
+			/* ... */
+		},
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+
+const mount = createPlayUI(registryResult, {
+	onRenderError: console.error,
+	fallback: document.getElementById("loading")!,
+	navigate: (path) => myRouter.push(path),
+	functions: {
+		fullName: (args) => `${args.first} ${args.last}`,
+	},
+});
+
+const disconnect = mount(actor, document.getElementById("app")!);
+disconnect();
+```
+
+### `PlayRenderer` — class-based lifecycle control
+
+Use `PlayRenderer` directly when you need explicit `connect()` / `disconnect()` lifecycle control, or when integrating into a system that manages the renderer's lifetime externally.
+
+```typescript
+import { PlayRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+
+const registryResult = defineRegistry(catalog, { components, actions });
+
+const renderer = new PlayRenderer(container, actor, registryResult.registry, { registryResult });
+
+renderer.connect();
+// Later:
+renderer.disconnect();
+```
+
+**Controlled store mode** — supply an external `StateStore` so the renderer shares state with other parts of your app:
+
+```typescript
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
+
+const atom = createAtom({ username: "" });
+const store = xstateStoreStateStore({ atom });
+
+const renderer = new PlayRenderer(container, actor, registryResult.registry, {
+	registryResult,
+	store,
+});
+renderer.connect();
+```
+
+## Provider Options
+
+All entry points (`createPlayUI`, `PlayRenderer`) accept the same set of UI-provider options via `UIProviderOptions`. These are forwarded into `DomRenderContext` on every render pass, making them available to component implementations via `ctx.ctx.*`.
+
+### `functions` — named compute functions for `$computed` prop expressions
+
+Enables `{ "$computed": "name", "args": {...} }` dynamic prop values in specs. Each function receives the resolved `args` object and returns the computed value.
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	functions: {
+		fullName: (args) => `${args.first} ${args.last}`,
+		formatDate: (args) => new Date(args.iso as string).toLocaleDateString(),
+	},
+});
+```
+
+Without `functions`, any `$computed` expression silently resolves to `undefined` (no throw, backward-compatible).
+
+### `validationFunctions` — custom field validation
+
+Provides named validation functions for inline field validation within components. Functions receive `(value, args?)` and return `true` (valid) or `false` (invalid).
+
+Unlike the framework renderers, the DOM renderer has no automatic `ValidationProvider` tree. Components must invoke validation explicitly using `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`, passing `ctx.ctx.validationFunctions` as `customFunctions`.
+
+```typescript
+import { runValidationCheck } from "@xmachines/json-render-core";
+
+const mount = createPlayUI(registryResult, {
+	validationFunctions: {
+		isEven: (value) => typeof value === "number" && value % 2 === 0,
+		phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)),
+	},
+});
+
+// Inside a ComponentFn:
+const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => {
+	const result = runValidationCheck(
+		{ type: "isEven", message: "must be even" },
+		{ value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions },
+	);
+	// result.valid, result.message
+};
+```
+
+### `navigate` — programmatic navigation from action bindings
+
+A callback invoked when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Integrate with any router:
+
+```typescript
+// React Router / TanStack Router / any push-based router:
+const mount = createPlayUI(registryResult, {
+	navigate: (path) => myRouter.push(path),
+});
+```
+
+With a spec binding:
+
+```json
+{
+	"on": {
+		"click": {
+			"action": "submitForm",
+			"onSuccess": { "navigate": "/dashboard" }
+		}
+	}
+}
+```
+
+When `submitForm` completes successfully, `navigate("/dashboard")` is called automatically.
+
+The function is also readable by component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding.
+
+### `onRenderError` — unified error handler
+
+Receives `(error, name)` for three distinct error classes:
+
+- **Component render errors** — when a `ComponentFn` throws synchronously during `renderSpec`. `name` is the catalog component name (e.g. `"Home"`).
+- **Action handler rejections (emit path)** — when an `ActionFn` throws or returns a rejected promise during `emit()`. `name` is the catalog action name (e.g. `"submitForm"`).
+- **Action handler rejections (watch path)** — when an `ActionFn` rejects during a `watch` binding callback. `name` is the catalog action name.
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	onRenderError: (err, name) => {
+		// Route to your application's error tracking
+		Sentry.captureException(err, { extra: { name } });
+	},
+});
+```
+
+The argument order matches the upstream `RenderErrorHandler` type from `@xmachines/json-render-core`: **error first, name second**. This is consistent with the framework renderers (`@xmachines/json-render-solid`, `@xmachines/json-render-react`).
+
+Without `onRenderError`, all three error types are logged via `console.error` and swallowed. No exception propagates, and no unhandled promise rejection is created.
+
+The handler is also available to component implementations via `ctx.ctx.onRenderError`, enabling components to route their own internal errors through the same channel:
+
+```typescript
+const MyComponent: ComponentFn<typeof catalog, "MyComponent"> = ({ ctx }) => {
+	try {
+		const el = doSomethingRisky();
+		return el;
+	} catch (err) {
+		ctx.ctx.onRenderError?.(err, "MyComponent");
+		return null;
+	}
+};
+```
+
+## API Summary
+
+### XMachines Layer
+
+| Export                                   | Kind     | Description                                                                 |
+| ---------------------------------------- | -------- | --------------------------------------------------------------------------- |
+| `createRenderer(catalog, components)`    | function | One-call factory — returns `mount(actor, container, options?) → disconnect` |
+| `createPlayUI(registryResult, options?)` | function | Batteries-included factory — returns `MountFn`                              |
+| `PlayRenderer`                           | class    | Class-based renderer with `connect()` / `disconnect()` lifecycle            |
+| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                     |
+| `renderSpec(...)`                        | function | Pure Spec → DOM renderer (low-level)                                        |
+| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()`         |
+
+### Key Types
+
+| Type                     | Description                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------ |
+| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                   |
+| `ComponentContext<C, K>` | Context passed to each component: `props`, `children`, `emit`, `on`, `bindings`, `ctx`     |
+| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                       |
+| `EventHandle`            | Handle returned by `on(eventName)` — has `emit()`, `shouldPreventDefault`, `bound`         |
+| `SetState`               | State updater: `(prev => next) => void`                                                    |
+| `DefineRegistryResult`   | Result from `defineRegistry` — has `registry`, `handlers`, `executeAction`                 |
+| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`                                   |
+| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback`                  |
+| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                        |
+| `MountFn`                | The mount function returned by `createPlayUI`: `(actor, container, options?) → disconnect` |
+| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`            |
+| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                            |
+| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                  |
+| `DomSchema`              | Type of the `schema` export                                                                |
+| `ComputedFunction`       | Type for named compute functions used with the `functions` option                          |
+
+## Rendering Behaviour
+
+- **Initial render is synchronous** — the container is populated before `connect()` returns.
+- **Signal-driven re-renders are microtask-deferred** — `watchSignal` schedules updates on the next microtask queue tick.
+- **Null view** clears the container. A `fallback` element can be shown on initial mount when the view is `null`; it is **not** re-appended if the view later transitions back to `null` after a non-null view.
+- **Double `connect()` is safe** — calling `connect()` on an already-connected renderer auto-disconnects first.
+- **`disconnect()` clears the container** and unsubscribes all signal and store watchers.
+
+## Testing
+
+```bash
+# Run all tests (jsdom environment)
+pnpm test
+
+# Run with coverage
+pnpm run test:coverage
+```
+
+Tests live in `test/` and use [Vitest](https://vitest.dev/) with a jsdom environment. Coverage thresholds: 80% lines, functions, branches, and statements.
+
+@xmachines/play-dom — Vanilla DOM renderer for XMachines Play architecture.
+
+Public API split into two layers:
+
+**XMachines layer** (this package):
+
+- `createRenderer()` — one-call factory: returns `mount(actor, container, options?) → disconnect`
+- `createPlayUI()` — batteries-included factory with full options: returns `MountFn`
+- `PlayRenderer` — class-based renderer with `connect()` / `disconnect()` lifecycle
+- `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `MountOptions`
+
+**json-render layer** (re-exported from @xmachines/json-render-dom):
+
+- `defineRegistry` — build a catalog-typed DomRegistry
+- `renderSpec` — pure Spec → DOM renderer (uses resolveElementProps from core)
+- `ComponentFn` — catalog-typed component function type
+- `ComponentContext` — catalog-typed render context (props, emit, on, children, bindings)
+- `ComponentRegistry` — catalog-typed registry input type
+- `DomComponentRenderer` — raw element-level renderer type
+- `DomRegistry` — raw registry type
+- `DomRenderContext` — raw render context
+- `EventHandle` — event handle returned by on()
+- `SetState` — state updater function passed to ActionFn
+- `CatalogHasActions` — conditional type: true when catalog declares actions
+- `BaseComponentProps` — base props type for catalog component definitions
+
+## Classes
+
+- [PlayRenderer](classes/PlayRenderer.md)
+
+## Interfaces
+
+- [ComponentContext](interfaces/ComponentContext.md)
+- [CreatePlayUIOptions](interfaces/CreatePlayUIOptions.md)
+- [DefineRegistryResult](interfaces/DefineRegistryResult.md)
+- [DomRenderContext](interfaces/DomRenderContext.md)
+- [EventHandle](interfaces/EventHandle.md)
+- [MountOptions](interfaces/MountOptions.md)
+- [PlayDomOptions](interfaces/PlayDomOptions.md)
+- [RenderSpecOptions](interfaces/RenderSpecOptions.md)
+- [UIProviderOptions](interfaces/UIProviderOptions.md)
+
+## Type Aliases
+
+- [ActionFn](type-aliases/ActionFn.md)
+- [Actions](type-aliases/Actions.md)
+- [BaseComponentProps](type-aliases/BaseComponentProps.md)
+- [CatalogHasActions](type-aliases/CatalogHasActions.md)
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [ComponentRegistry](type-aliases/ComponentRegistry.md)
+- [ConfirmHandler](type-aliases/ConfirmHandler.md)
+- [DefineRegistryOptions](type-aliases/DefineRegistryOptions.md)
+- [DomComponentRenderer](type-aliases/DomComponentRenderer.md)
+- [DomRegistry](type-aliases/DomRegistry.md)
+- [DomSchema](type-aliases/DomSchema.md)
+- [MountFn](type-aliases/MountFn.md)
+- [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
+- [SetState](type-aliases/SetState.md)
+
+## Variables
+
+- [schema](variables/schema.md)
+
+## Functions
+
+- [createPlayUI](functions/createPlayUI.md)
+- [createRenderer](functions/createRenderer.md)
+- [defineRegistry](functions/defineRegistry.md)
+- [renderSpec](functions/renderSpec.md)

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

@@ -0,0 +1,115 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / PlayRenderer
+
+# Class: PlayRenderer
+
+Defined in: [packages/play-dom/src/PlayRenderer.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/PlayRenderer.ts#L67)
+
+PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
+
+Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
+functions into `container` on every view transition. Cleared on `disconnect()`.
+
+Options from `PlayDomOptions` (which extends `UIProviderOptions`) are all forwarded
+into `DomRenderContext` on every render pass:
+
+- `functions` — named compute functions for `{ $computed: "name" }` prop expressions
+- `directives` — custom `$`-prefixed dynamic values (from `defineDirective`), resolved during prop resolution
+- `validationFunctions` — custom validation functions, available at `ctx.ctx.validationFunctions`
+- `navigate` — navigation callback, invoked on `onSuccess: { navigate: "..." }` action bindings
+- `onRenderError` — called with `(error, name)` for component render errors and action handler rejections
+
+**Preferred usage — via `registryResult`:**
+
+```typescript
+import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+
+const registryResult = defineRegistry(catalog, { components, actions });
+const renderer = new PlayRenderer(container, actor, registryResult.registry, {
+	registryResult, // wires setState/getState from xstate store automatically
+	navigate: (path) => myRouter.push(path),
+	functions: { fullName: (args) => `${args.first} ${args.last}` },
+});
+renderer.connect();
+// Later:
+renderer.disconnect();
+```
+
+**Controlled store mode** — bring your own `StateStore`:
+
+```typescript
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
+
+const atom = createAtom({ username: "" });
+const store = xstateStoreStateStore({ atom });
+const renderer = new PlayRenderer(container, actor, registry, { registryResult, store });
+renderer.connect();
+```
+
+Double `connect()` is safe — calling `connect()` while already connected
+automatically disconnects first, preventing double-render subscriptions.
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlayRenderer(
+   container,
+   actor,
+   registry,
+   options?): PlayRenderer;
+```
+
+Defined in: [packages/play-dom/src/PlayRenderer.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/PlayRenderer.ts#L102)
+
+#### Parameters
+
+| Parameter   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container` | `HTMLElement`                                                                                                                                                                                                                                                    | `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 providing the `currentView` signal (must implement `Viewable`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `registry`  | [`DomRegistry`](../type-aliases/DomRegistry.md)                                                                                                                                                                                                                  | Component renderer map — typically `registryResult.registry` from `defineRegistry`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `options`   | [`PlayDomOptions`](../interfaces/PlayDomOptions.md)                                                                                                                                                                                                              | Configuration (see [PlayDomOptions](../interfaces/PlayDomOptions.md)): - `registryResult` — auto-wires `setState`/`state` from the xstate store. - `store` — external `StateStore` (controlled mode; overrides `spec.state` seeding). - `loading` — streaming mode flag; suppresses missing-child warnings. - `functions` — named compute functions for `$computed` prop expressions. - `directives` — custom `$`-prefixed dynamic values resolved during prop resolution. - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`. - `navigate` — navigation callback; invoked on `onSuccess: { navigate: "..." }`. - `onRenderError` — `(error, name)` handler for component render errors and action handler rejections; suppresses `console.error` fallback. |
+
+#### Returns
+
+`PlayRenderer`
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: [packages/play-dom/src/PlayRenderer.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/PlayRenderer.ts#L118)
+
+Start watching actor.currentView and render to container.
+Renders the initial view synchronously, then subscribes to signal changes.
+
+Calling `connect()` on an already-connected renderer (where a previous
+`connect()` was never followed by `disconnect()`) would silently install a
+second `watchSignal` subscription, causing double-renders on every view
+change. Guard against this by auto-disconnecting first.
+
+#### Returns
+
+`void`
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: [packages/play-dom/src/PlayRenderer.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/PlayRenderer.ts#L127)
+
+Stop watching and clear the container.
+
+#### Returns
+
+`void`