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

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

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

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

@@ -2,34 +2,42 @@
 
 # Class: PlayRenderer
 
-Defined in: [PlayRenderer.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L60)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/PlayRenderer.ts#L78)
 
-PlayRenderer connects an actor's currentView signal to the DOM renderer.
+PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
 
-Usage:
+Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
+functions into `container` on every view transition. Cleared on `disconnect()`.
+
+**Preferred usage — via `registryResult`:**
 
 ```typescript
-const { registry, handlers } = defineRegistry(catalog, { components, actions });
-const resolvedHandlers = handlers(
-	() => undefined,
-	() => ({}),
-);
-const renderer = new PlayRenderer(container, actor, registry, { handlers: resolvedHandlers });
+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
+});
 renderer.connect();
+// Later:
+renderer.disconnect();
+```
+
+**Controlled store mode** — bring your own `StateStore`:
 
-// Controlled mode — bring your own store:
+```typescript
 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,
-	handlers: resolvedHandlers,
-});
 
-// Later:
-renderer.disconnect();
+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
@@ -42,16 +50,16 @@ new PlayRenderer(
    options?): PlayRenderer;
 ```
 
-Defined in: [PlayRenderer.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L72)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/PlayRenderer.ts#L101)
 
 #### 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: `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`). |
+| 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: - `registryResult` — preferred; auto-wires `setState`/`state` from the xstate store. - `handlers` — pre-resolved handler map (legacy; used when `registryResult` is absent). - `store` — external `StateStore` (controlled mode; overrides `spec.state` seeding). - `loading` — streaming mode flag; suppresses missing-child warnings. |
 
 #### Returns
 
@@ -65,11 +73,16 @@ Defined in: [PlayRenderer.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/bl
 connect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L83)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/PlayRenderer.ts#L117)
 
 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`
@@ -82,7 +95,7 @@ Renders the initial view synchronously, then subscribes to signal changes.
 disconnect(): void;
 ```
 
-Defined in: [PlayRenderer.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/PlayRenderer.ts#L91)
+Defined in: [packages/play-dom/src/PlayRenderer.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/PlayRenderer.ts#L126)
 
 Stop watching and clear the container.
 

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

@@ -6,46 +6,65 @@
 function connectRenderer(options): () => void;
 ```
 
-Defined in: [connect-renderer.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/connect-renderer.ts#L46)
+Defined in: [packages/play-dom/src/connect-renderer.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/connect-renderer.ts#L65)
 
-Connect a signal-driven DOM renderer to an actor's currentView signal.
+Connect a signal-driven DOM renderer to an actor's `currentView` signal.
 
-Subscribes to `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
-functions into the provided `container` element on every state change.
+Subscribes to `actor.currentView` via TC39 Signals and renders catalog-typed
+components into `container` on every view transition. Clears the container
+when the view is `null` (optionally appends `fallback` on initial mount).
 
-- Renders the initial view immediately (synchronous)
-- Re-renders when `actor.currentView` signal changes (via microtask)
-- Clears container when view is `null` (optionally appends fallback)
+- Initial render is **synchronous** — the container is populated before `connectRenderer` returns.
+- Signal-driven re-renders are **microtask-deferred** — `watchSignal` schedules them
+  on the next microtask queue tick, not synchronously within the signal update.
+
+For the one-call pattern, prefer [createRenderer](createRenderer.md) which wraps `defineRegistry`
+and `PlayRenderer` into a single factory function.
 
 ## Parameters
 
-| Parameter | Type                                                                | Description            |
-| --------- | ------------------------------------------------------------------- | ---------------------- |
-| `options` | [`ConnectRendererOptions`](../interfaces/ConnectRendererOptions.md) | ConnectRendererOptions |
+| Parameter | Type                                                                | Description                                                       |
+| --------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `options` | [`ConnectRendererOptions`](../interfaces/ConnectRendererOptions.md) | [ConnectRendererOptions](../interfaces/ConnectRendererOptions.md) |
 
 ## Returns
 
-A cleanup function that stops all DOM mutations
+A cleanup function — call to stop all DOM mutations and remove subscriptions.
 
 () => `void`
 
 ## Example
 
 ```typescript
-import { connectRenderer, type DomComponentRenderer } from "@xmachines/play-dom";
+import { connectRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
 
-const unwatch = connectRenderer({
-	actor,
-	registry: {
-		Home: (element, ctx) => {
-			const el = document.createElement("div");
-			el.textContent = element.props.title as string;
+const catalog = defineCatalog(schema, {
+	components: { Home: { props: z.object({ title: z.string() }) } },
+	actions: { logout: {} },
+});
+
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: ({ props }) => {
+			const el = document.createElement("section");
+			el.textContent = props.title;
 			return el;
 		},
 	},
+	actions: {
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+
+const disconnect = connectRenderer({
+	actor,
+	registry: registryResult.registry,
+	registryResult, // preferred — wires setState/state from xstate store automatically
 	container: document.getElementById("app")!,
 });
 
-// Later: stop watching
-unwatch();
+// Later:
+disconnect();
 ```