@xmachines/play-dom 1.0.0-beta.45 → 1.0.0-beta.47

package/README.md

@@ -1,106 +1,24 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-dom
 
-**Vanilla DOM renderer for XMachines**
+Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
 
-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`.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install @xmachines/play-dom @json-render/core zod
+npm install @xmachines/play-dom
 ```
 
-## Key Exports
-
-| 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";
+**Peer dependencies:**
 
-// 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();
-
-const disconnect = ui.mount(actor, document.getElementById("app")!);
-
-// Cleanup:
-disconnect();
+```bash
+npm install xstate @xstate/store @json-render/core @json-render/xstate
 ```
 
-## Quick Start — `createRenderer`
-
-The lower-level one-call pattern — takes a catalog and component map directly:
+## Quick Start
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
@@ -108,7 +26,7 @@ import { defineCatalog } from "@json-render/core";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
 
-// 1. Define catalog
+// 1. Define a catalog
 const catalog = defineCatalog(schema, {
 	components: {
 		Home: { props: z.object({ title: z.string() }) },
@@ -119,210 +37,200 @@ const catalog = defineCatalog(schema, {
 		logout: {},
 	},
 });
-type AppCatalog = typeof catalog;
 
 // 2. Implement components
-const Home: ComponentFn<AppCatalog, "Home"> = ({ props }) => {
+const Home: ComponentFn<typeof catalog, "Home"> = ({ props }) => {
 	const el = document.createElement("section");
 	el.textContent = props.title;
 	return el;
 };
 
-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 Login: ComponentFn<typeof catalog, "Login"> = ({ props, on }) => {
+	const el = document.createElement("section");
+	const btn = document.createElement("button");
 	const submit = on("submit");
-	button.addEventListener("click", () => submit.emit());
-
-	section.append(input, button);
-	return section;
+	btn.addEventListener("click", () => submit.emit());
+	el.append(btn);
+	return el;
 };
 
-// 3. Create the renderer factory (once, at module level)
+// 3. Build the factory once (module scope)
 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:
+// 5. Cleanup on teardown
 disconnect();
 ```
 
-## `defineRegistry` — Full Control
+## Usage
 
-When you need `registryResult.executeAction()` or want to share the registry with `connectRenderer`:
+### `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 { defineRegistry, connectRenderer, schema } from "@xmachines/play-dom";
+import { createRenderer, 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: { params: z.object({ username: z.string() }) },
-		logout: {},
-	},
+	/* ... */
+});
+
+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, or a shared `registryResult` that you also need to reference programmatically (e.g. for `executeAction`).
+
+```typescript
+import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+
+const catalog = defineCatalog(schema, {
+	/* ... */
 });
 
-// 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;
-		},
-	},
+	components: { Home, Login },
 	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" }),
 	},
 });
 
-const disconnect = connectRenderer({
-	actor,
-	registry: registryResult.registry,
-	registryResult, // wires setState/state from xstate store automatically
-	container: document.getElementById("app")!,
+const mount = createPlayUI(registryResult, {
+	onRenderError: console.error,
+	fallback: document.getElementById("loading")!,
 });
+
+const disconnect = mount(actor, document.getElementById("app")!);
+disconnect();
 ```
 
-## Component API
+### `PlayRenderer` — class-based lifecycle control
 
-### `ComponentFn<C, K>` — component function signature
+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
-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;
-};
-```
+import { PlayRenderer, defineRegistry, schema } from "@xmachines/play-dom";
 
-### Two-way binding with `$bindState`
+const registryResult = defineRegistry(catalog, { components, actions });
 
-In the view spec:
+const renderer = new PlayRenderer(container, actor, registryResult.registry, { registryResult });
 
-```json
-{ "username": { "$bindState": "/username" } }
+renderer.connect();
+// Later:
+renderer.disconnect();
 ```
 
-In the component:
+**Controlled store mode** — supply an external `StateStore` so the renderer shares state with other parts of your app:
 
 ```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;
-};
-```
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
 
-### `on()` — event handle
+const atom = createAtom({ username: "" });
+const store = xstateStoreStateStore({ atom });
 
-```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
-	});
-}
+const renderer = new PlayRenderer(container, actor, registryResult.registry, {
+	registryResult,
+	store,
+});
+renderer.connect();
 ```
 
-### `ActionFn` — action handler signature
+### `connectRenderer` — functional API (backward-compatible)
+
+`connectRenderer` is the original functional API, equivalent to creating a `PlayRenderer` and calling `connect()` in one step. Prefer `createRenderer` or `createPlayUI` for new code.
 
 ```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 }),
-```
+import { connectRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+
+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" }),
+	},
+});
 
-## Spec Features
+const disconnect = connectRenderer({
+	actor,
+	registry: registryResult.registry,
+	registryResult,
+	container: document.getElementById("app")!,
+});
 
-`renderSpec` / `renderElement` supports these spec directives:
+// Later:
+disconnect();
+```
 
-| 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                                                     |
+## API Summary
 
-## `PlayRenderer` — class API
+### XMachines Layer
 
-```typescript
-import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+| 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            |
+| `connectRenderer(options)`               | function | Functional API; backward-compatible alternative to `PlayRenderer`           |
+| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                     |
+| `renderSpec(...)`                        | function | Pure Spec → DOM renderer (low-level)                                        |
+| `schema`                                 | const    | The `@json-render/dom` schema — pass to `defineCatalog()`                   |
 
-const { registry, registryResult } = defineRegistry(catalog, { components, actions });
+### Key Types
 
-const renderer = new PlayRenderer(document.getElementById("app")!, actor, registry, {
-	registryResult,
-});
+| 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` and `connectRenderer`                                       |
+| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                        |
+| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                              |
+| `DomSchema`              | Type of the `schema` export                                                            |
 
-renderer.connect(); // starts watching actor.currentView
-renderer.disconnect(); // stops watching, clears container
+### Error Classes
 
-// double-connect is safe — connect() calls disconnect() internally if already connected
-```
+| Class                   | Error Code                        | Description                              |
+| ----------------------- | --------------------------------- | ---------------------------------------- |
+| `MissingCatalogError`   | `PLAY_RENDERER_MISSING_CATALOG`   | Components map was `null` or `undefined` |
+| `MissingComponentError` | `PLAY_RENDERER_MISSING_COMPONENT` | Component name not found in catalog      |
 
-## Options Reference
+## Rendering Behaviour
 
-### `ConnectRendererOptions` / `PlayDomOptions`
+- **Initial render is synchronous** — the container is populated before `connect()` or `connectRenderer()` 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.
 
-| 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` |
+## Testing
 
-## Learn More
+```bash
+# Run all tests (jsdom environment)
+npm test
+
+# Run with coverage
+npm run test:coverage
+```
 
-- [Demo](examples/demo/README.md)
-- [DOM Router adapter](../play-dom-router/README.md)
-- [Play RFC](../../packages/docs/rfc/play.md)
+Tests live in `test/` and use [Vitest](https://vitest.dev/) with a jsdom environment. Coverage thresholds: 80% lines, functions, branches, and statements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-dom",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.47",
   "description": "Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering",
   "keywords": [
     "actor",
@@ -43,15 +43,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play": "1.0.0-beta.45",
-    "@xmachines/play-actor": "1.0.0-beta.45",
-    "@xmachines/play-signals": "1.0.0-beta.45"
+    "@xmachines/play": "1.0.0-beta.47",
+    "@xmachines/play-actor": "1.0.0-beta.47",
+    "@xmachines/play-signals": "1.0.0-beta.47"
   },
   "devDependencies": {
     "@json-render/core": "^0.18.0",
     "@json-render/xstate": "^0.18.0",
     "@types/node": "^25.6.0",
-    "@xmachines/shared": "1.0.0-beta.45",
+    "@xmachines/shared": "1.0.0-beta.47",
     "@xstate/store": "^3.17.0",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0",