@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,14 +2,14 @@
 
 # Interface: ViewStoreResolution
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L35)
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L38)
 
-What a resolve produced — see [ViewStoreLifecycle.resolve](ViewStoreLifecycle.md#resolve).
+The result of a resolve — see [ViewStoreLifecycle.resolve](ViewStoreLifecycle.md#resolve).
 
 ## Properties
 
-| Property                                          | Type         | Description                                                                                                                                                                                                   | Defined in                                                                                                                                                         |
-| ------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-guardedstore"></a> `guardedStore` | `StateStore` | The store to hand children ($bindState, setState, chained set): writes under /context throw. One wrapper per underlying store — the identity is cached so `useSyncExternalStore`-style consumers stay stable. | [packages/play-actor/src/view-store-lifecycle.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L43) |
-| <a id="property-reseeded"></a> `reseeded`         | `boolean`    | True when this resolve created a fresh store (first resolve, viewKey change, per-emission fallback, actor swap). Providers that remount a subtree per store (Vue's storeKey) key on it.                       | [packages/play-actor/src/view-store-lifecycle.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L49) |
-| <a id="property-store"></a> `store`               | `StateStore` | The UNGUARDED store — the machinery's own refresh reference.                                                                                                                                                  | [packages/play-actor/src/view-store-lifecycle.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/view-store-lifecycle.ts#L37) |
+| Property                                          | Type         | Description                                                                                                                                                                                                                                                                       | Defined in                                                                                                                                                         |
+| ------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-guardedstore"></a> `guardedStore` | `StateStore` | The store to give to the children ($bindState, setState, and a chained set): a write under /context throws. There is one wrapper for each store below it, and the code caches the identity. Therefore a consumer in the style of `useSyncExternalStore` stays stable.             | [packages/play-actor/src/view-store-lifecycle.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L47) |
+| <a id="property-reseeded"></a> `reseeded`         | `boolean`    | It is true when this resolve made a new store: at the first resolve, on a change of the viewKey, in the fallback for each emission, and on a change of the actor. A provider that mounts a subtree again for each store, such as the storeKey of Vue, uses this field as its key. | [packages/play-actor/src/view-store-lifecycle.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L54) |
+| <a id="property-store"></a> `store`               | `StateStore` | The store WITHOUT the guard — the reference of the machinery for its own refresh.                                                                                                                                                                                                 | [packages/play-actor/src/view-store-lifecycle.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/view-store-lifecycle.ts#L40) |

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

@@ -2,17 +2,17 @@
 
 # Interface: Viewable
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L101)
+Defined in: [packages/play-actor/src/abstract-actor.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L103)
 
-Actor capability for exposing renderable view state.
+The actor capability that exposes a 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.
+`Viewable` marks an actor that publishes a `currentView` signal.
+A renderer, such as `PlayRenderer`, reads this contract. It converts the
+description of the current view into a concrete UI, and the framework adapter
+therefore holds no view logic.
 
 ## Properties
 
-| 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:108](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L108) |
+| 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`\> | The signal of the current view. It holds the json-render PlaySpec of the current machine state, or null when no view is active. The infrastructure renders the view. This is the Logic-Driven UI invariant. | [packages/play-actor/src/abstract-actor.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L110) |

package/api/@xmachines/play-actor/variables/CONTEXT_STATE_KEY.md

@@ -6,10 +6,10 @@
 const CONTEXT_STATE_KEY: "context" = "context";
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/context-projection.ts#L31)
+Defined in: [packages/play-actor/src/context-projection.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/context-projection.ts#L32)
 
-The reserved top-level state key the projection materializes under.
+The reserved top-level state key of the projection.
 
-A view's authored `spec.state` must not declare this key — when it does, the
-projection is skipped for that view (the authored state wins) and a dev
-warning is emitted. See [composePlayState](../functions/composePlayState.md).
+The `spec.state` object of a view must not declare this key. When it does, the
+derivation skips the projection for that view, the authored state wins, and the
+code writes a warning in development. See [composePlayState](../functions/composePlayState.md).

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

@@ -4,9 +4,7 @@
 
 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-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
-
-Part of the [XMachines Play monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -24,7 +22,9 @@ pnpm add xstate @xstate/store @xmachines/json-render-core @xmachines/json-render
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
+import { definePlayer } from "@xmachines/play-xstate";
 import { defineCatalog } from "@xmachines/json-render-core";
+import { createMachine } from "xstate";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
 
@@ -59,10 +59,36 @@ const Login: ComponentFn<typeof catalog, "Login"> = ({ props, on }) => {
 // 3. Build the factory once (module scope)
 const mount = createRenderer(catalog, { Home, Login });
 
-// 4. Mount when actor and container are ready
+// 4. Create and start an actor — states carry meta.view specs naming catalog components
+const machine = createMachine({
+	initial: "home",
+	states: {
+		home: {
+			on: { "goto.login": "login" },
+			meta: {
+				view: {
+					root: "root",
+					elements: { root: { type: "Home", props: { title: "Home" }, children: [] } },
+				},
+			},
+		},
+		login: {
+			meta: {
+				view: {
+					root: "root",
+					elements: { root: { type: "Login", props: { title: "Login" }, children: [] } },
+				},
+			},
+		},
+	},
+});
+const actor = definePlayer({ machine })();
+actor.start();
+
+// 5. Mount when actor and container are ready
 const disconnect = mount(actor, document.getElementById("app")!);
 
-// 5. Cleanup on teardown
+// 6. Cleanup on teardown
 disconnect();
 ```
 
@@ -70,7 +96,7 @@ disconnect();
 
 ### `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.
+`createRenderer` is the simplest integration path. Call it one time at module scope, with your catalog and your component map. Then call the `mount` function that it returns, one time for each pair of an actor and a container.
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
@@ -80,16 +106,17 @@ const catalog = defineCatalog(schema, {/* ... */});
 
 const mount = createRenderer(catalog, { MyComponent });
 
+// actor from the Quick Start
 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
+### `createPlayUI` — the complete factory with every option
 
-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`).
+Use `createPlayUI` when you need a render error handler, a fallback element, a navigation integration, a computed function, or a custom check. Use it also when your code needs the `registryResult` value, for example 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.
+The factory holds the factory options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and it applies them on every `mount()` call. Give the mount options (`store` and `loading`) to `mount()` itself.
 
 ```typescript
 import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
@@ -97,6 +124,7 @@ import { defineCatalog } from "@xmachines/json-render-core";
 
 const catalog = defineCatalog(schema, {/* ... */});
 
+// Home, Login, actor from the Quick Start
 const registryResult = defineRegistry(catalog, {
 	components: { Home, Login },
 	actions: {
@@ -122,13 +150,15 @@ 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.
+Use `PlayRenderer` directly when you need the explicit `connect()` and `disconnect()` control, or when you integrate the renderer into a system that controls its life itself.
 
 ```typescript
 import { PlayRenderer, defineRegistry, schema } from "@xmachines/play-dom";
 
+// catalog, actor from the Quick Start; components/actions as in the createPlayUI example
 const registryResult = defineRegistry(catalog, { components, actions });
 
+// container: your mount element, e.g. document.getElementById("app")!
 const renderer = new PlayRenderer(container, actor, registryResult.registry, { registryResult });
 
 renderer.connect();
@@ -136,15 +166,16 @@ renderer.connect();
 renderer.disconnect();
 ```
 
-**Controlled store mode** — supply an external `StateStore` so the renderer shares state with other parts of your app:
+**Controlled store mode.** Give the renderer an external `StateStore`. The renderer then shares the state with the other parts of your application:
 
 ```typescript
 import { createAtom } from "@xstate/store";
 import { xstateStoreStateStore } from "@xmachines/json-render-xstate";
 
-const atom = createAtom({ username: "" });
+const atom = createAtom<Record<string, unknown>>({ username: "" });
 const store = xstateStoreStateStore({ atom });
 
+// container, actor, registryResult from the previous example
 const renderer = new PlayRenderer(container, actor, registryResult.registry, {
 	registryResult,
 	store,
@@ -154,11 +185,11 @@ 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.*`.
+Every entry point (`createPlayUI` and `PlayRenderer`) accepts the same UI-provider options, through `UIProviderOptions`. Each render pass puts the options into `DomRenderContext`. A component implementation therefore reads them at `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.
+This option permits a dynamic prop value of the form `{ "$computed": "name", "args": {...} }` in a spec. Each function receives the resolved `args` object, and it returns the computed value.
 
 ```typescript
 const mount = createPlayUI(registryResult, {
@@ -169,13 +200,13 @@ const mount = createPlayUI(registryResult, {
 });
 ```
 
-Without `functions`, any `$computed` expression silently resolves to `undefined` (no throw, backward-compatible).
+Without `functions`, every `$computed` expression resolves to `undefined`. Nothing throws, and the old behavior stays.
 
 ### `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).
+This option gives the named check functions for a field check inside a component. Each function receives `(value, args?)`. It returns `true` for a valid value, or `false` for an invalid value.
 
-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`.
+The DOM renderer has no `ValidationProvider` tree, and in this it is different from the framework renderers. Each component must call the check itself, with `runValidationCheck` or `runValidation` from `@xmachines/json-render-core`. Give `ctx.ctx.validationFunctions` to the call as `customFunctions`.
 
 ```typescript
 import { runValidationCheck } from "@xmachines/json-render-core";
@@ -187,19 +218,21 @@ const mount = createPlayUI(registryResult, {
 	},
 });
 
-// Inside a ComponentFn:
-const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => {
+// Inside a ComponentFn (catalog from the Quick Start):
+const Login: ComponentFn<typeof catalog, "Login"> = ({ ctx }) => {
+	const someValue = 42; // the value to validate, e.g. read from an input
 	const result = runValidationCheck(
 		{ type: "isEven", message: "must be even" },
 		{ value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions },
 	);
 	// result.valid, result.message
+	return null;
 };
 ```
 
 ### `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:
+The renderer calls this callback when an action binding resolves with `onSuccess: { navigate: "/path" }`. The callback receives the resolved path string as its only argument. Use it with every router:
 
 ```typescript
 // React Router / TanStack Router / any push-based router:
@@ -221,17 +254,17 @@ With a spec binding:
 }
 ```
 
-When `submitForm` completes successfully, `navigate("/dashboard")` is called automatically.
+`submitForm` completes without an error, and the renderer then calls `navigate("/dashboard")`.
 
-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.
+A component implementation can also read the function at `ctx.ctx.navigate`. Use this when a navigation must start outside an action binding.
 
 ### `onRenderError` — unified error handler
 
-Receives `(error, name)` for three distinct error classes:
+The handler receives `(error, name)` for three different classes of error:
 
-- **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.
+- **A component render error** — a `ComponentFn` throws synchronously during `renderSpec`. `name` is then the catalog component name, for example `"Home"`.
+- **An action handler rejection on the emit path** — an `ActionFn` throws, or it returns a rejected promise, during `emit()`. `name` is then the catalog action name, for example `"submitForm"`.
+- **An action handler rejection on the watch path** — an `ActionFn` rejects during a `watch` binding callback. `name` is then the catalog action name.
 
 ```typescript
 const mount = createPlayUI(registryResult, {
@@ -242,19 +275,20 @@ const mount = createPlayUI(registryResult, {
 });
 ```
 
-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`).
+The order of the arguments is the same as in the `RenderErrorHandler` type of `@xmachines/json-render-core`: **the error first, the name second**. The framework renderers (`@xmachines/json-render-solid` and `@xmachines/json-render-react`) use the same order.
 
-Without `onRenderError`, all three error types are logged via `console.error` and swallowed. No exception propagates, and no unhandled promise rejection is created.
+Without `onRenderError`, the renderer writes all three types of error to `console.error`, then stops them. No exception goes to the caller, and no promise rejection stays unhandled.
 
-The handler is also available to component implementations via `ctx.ctx.onRenderError`, enabling components to route their own internal errors through the same channel:
+A component implementation can also read the handler at `ctx.ctx.onRenderError`. A component therefore sends its own internal errors through the same channel:
 
 ```typescript
-const MyComponent: ComponentFn<typeof catalog, "MyComponent"> = ({ ctx }) => {
+// catalog from the Quick Start; doSomethingRisky: your render logic that may throw
+const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 	try {
 		const el = doSomethingRisky();
 		return el;
 	} catch (err) {
-		ctx.ctx.onRenderError?.(err, "MyComponent");
+		ctx.ctx.onRenderError?.(err, "Home");
 		return null;
 	}
 };
@@ -264,42 +298,42 @@ const MyComponent: ComponentFn<typeof catalog, "MyComponent"> = ({ ctx }) => {
 
 ### 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()`         |
+| Export                                   | Kind     | Description                                                                       |
+| ---------------------------------------- | -------- | --------------------------------------------------------------------------------- |
+| `createRenderer(catalog, components)`    | function | The one-call factory. It returns `mount(actor, container, options?) → disconnect` |
+| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `MountFn`                                      |
+| `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle               |
+| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                           |
+| `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                                            |
+| `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.
+| Type                     | Description                                                                                   |
+| ------------------------ | --------------------------------------------------------------------------------------------- |
+| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                      |
+| `ComponentContext<C, K>` | The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`       |
+| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                          |
+| `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound` |
+| `SetState`               | State updater: `(prev => next) => void`                                                       |
+| `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `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 that `createPlayUI` returns: `(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`       | The type of a named compute function for the `functions` option                               |
+
+## Rendering Behavior
+
+- **The first render is synchronous** — the renderer fills the container before `connect()` returns.
+- **A signal-driven render waits for a microtask** — `watchSignal` puts each update on the next tick of the microtask queue.
+- **A null view** clears the container. The renderer can show a `fallback` element on the first mount, when the view is `null`. It does **not** add that element again when the view returns to `null` after a view that was not null.
+- **A second `connect()` is safe** — a `connect()` call on a connected renderer disconnects it first.
+- **`disconnect()` clears the container** and cancels every signal watcher and store watcher.
 
 ## Testing
 
@@ -311,33 +345,33 @@ pnpm test
 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.
+The tests are in `test/`. They use [Vitest](https://vitest.dev/) in a jsdom environment. The coverage thresholds are 80% for lines, functions, branches, and statements.
 
-@xmachines/play-dom — Vanilla DOM renderer for XMachines Play architecture.
+@xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
 
-Public API split into two layers:
+The public API has two layers:
 
-**XMachines layer** (this package):
+**The XMachines layer**, in 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
+- `createRenderer()` — the one-call factory. It returns `mount(actor, container, options?) → disconnect`
+- `createPlayUI()` — the complete factory, with every option. It returns a `MountFn`
+- `PlayRenderer` — the renderer class, with a `connect()` and `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
+**The json-render layer**, re-exported from @xmachines/json-render-dom:
+
+- `defineRegistry` — it builds a catalog-typed DomRegistry
+- `renderSpec` — the pure Spec → DOM renderer. It uses resolveElementProps of the core
+- `ComponentFn` — the catalog-typed type of a component function
+- `ComponentContext` — the catalog-typed render context: props, emit, on, children, bindings
+- `ComponentRegistry` — the catalog-typed input type of the registry
+- `DomComponentRenderer` — the raw renderer type of one element
+- `DomRegistry` — the raw registry type
+- `DomRenderContext` — the raw render context
+- `EventHandle` — the event handle that on() returns
+- `SetState` — the state updater function of an ActionFn
+- `CatalogHasActions` — the conditional type. It is true when the catalog declares an action
+- `BaseComponentProps` — the base props type of a catalog component definition
 
 ## Classes