@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / createPlayUI
+
+# Function: createPlayUI()
+
+```ts
+function createPlayUI(registryResult, options?): MountFn;
+```
+
+Defined in: [packages/play-dom/src/create-play-ui.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/create-play-ui.ts#L93)
+
+Create a batteries-included DOM renderer mount function.
+
+The caller is responsible for producing `registryResult` via `defineRegistry`.
+`createPlayUI` closes over it and returns a `MountFn` that can be invoked
+once per actor/container pair.
+
+## Parameters
+
+| Parameter        | Type                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `registryResult` | [`DefineRegistryResult`](../interfaces/DefineRegistryResult.md) | Result from `defineRegistry()` — provides the registry and the lazy handlers factory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `options`        | [`CreatePlayUIOptions`](../interfaces/CreatePlayUIOptions.md)   | Factory-level configuration (see [CreatePlayUIOptions](../interfaces/CreatePlayUIOptions.md)): - `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. - `fallback` — element shown when the actor's initial view is `null`. |
+
+## Returns
+
+[`MountFn`](../type-aliases/MountFn.md)
+
+`MountFn`: `(actor, container, mountOptions?) → disconnect`

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

@@ -0,0 +1,44 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / createRenderer
+
+# Function: createRenderer()
+
+```ts
+function createRenderer<C>(catalog, componentMap): (actor, container, options?) => () => void;
+```
+
+Defined in: [packages/play-dom/src/create-renderer.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/create-renderer.ts#L84)
+
+Create a reusable DOM renderer factory from a catalog and component map.
+
+Returns a `mount(actor, container, options?)` function that wires up the
+PlayRenderer in one call and returns a `disconnect` cleanup function.
+
+## Type Parameters
+
+| Type Parameter                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------ |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\> |
+
+## Parameters
+
+| Parameter      | Type                                                               | Description                                                      |
+| -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `catalog`      | `C`                                                                | The json-render Catalog describing component and action schemas. |
+| `componentMap` | [`ComponentRegistry`](../type-aliases/ComponentRegistry.md)\<`C`\> | Component implementations keyed by catalog component name.       |
+
+## Returns
+
+A `mount` function that accepts `(actor, container, options?)` and returns `disconnect`.
+
+(`actor`, `container`, `options?`) => () => `void`
+
+## Remarks
+
+`createRenderer` manages `registryResult` internally — it calls `defineRegistry` once and
+reuses the result across all `mount()` calls. The `mount` options type therefore excludes
+`registryResult` (it is always provided by `createRenderer` itself and cannot be overridden).
+
+If you need to call `registryResult.executeAction()` programmatically (outside the emit/on
+flow), or pass additional provider options (`navigate`, `onRenderError`, `functions`, etc.),
+use `createPlayUI` (which accepts the full `CreatePlayUIOptions`) or `defineRegistry` with
+`PlayRenderer` directly rather than `createRenderer`.

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

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / defineRegistry
+
+# Function: defineRegistry()
+
+```ts
+function defineRegistry<C>(_catalog, options): DefineRegistryResult;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+## Type Parameters
+
+| Type Parameter                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------ |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\> |
+
+## Parameters
+
+| Parameter  | Type                                                                       |
+| ---------- | -------------------------------------------------------------------------- |
+| `_catalog` | `C`                                                                        |
+| `options`  | [`DefineRegistryOptions`](../type-aliases/DefineRegistryOptions.md)\<`C`\> |
+
+## Returns
+
+[`DefineRegistryResult`](../interfaces/DefineRegistryResult.md)

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

@@ -0,0 +1,67 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / renderSpec
+
+# Function: renderSpec()
+
+```ts
+function renderSpec(spec, store, registry, options?): Node | null;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+Render a Spec tree into DOM nodes using the provided `DomRegistry`.
+
+Traverses the spec from `spec.root`, evaluates visibility, resolves all prop
+expressions (including `$state`, `$bindState`, `$computed`, `$template`, etc.),
+and calls the matching `DomComponentRenderer` for each visible element.
+
+Event wiring and child rendering are handled inside the component wrapper
+built by `defineRegistry` — this function only orchestrates the traversal.
+
+## Parameters
+
+| Parameter  | Type                                                      | Description                                                                  |
+| ---------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `spec`     | `Spec`                                                    | The json-render `Spec` describing the UI tree.                               |
+| `store`    | `StateStore`                                              | Live `StateStore` bound to `spec.state`.                                     |
+| `registry` | [`DomRegistry`](../type-aliases/DomRegistry.md)           | Map of element type names → `DomComponentRenderer`.                          |
+| `options?` | [`RenderSpecOptions`](../interfaces/RenderSpecOptions.md) | Named options — see [RenderSpecOptions](../interfaces/RenderSpecOptions.md). |
+
+## Returns
+
+`Node` \| `null`
+
+The root DOM `Node`, or `null` if the root is invisible
+or has no registered renderer.
+
+## Remarks
+
+**Devtools isolation in tests:** The module-level `devtoolsActive` flag is a
+singleton that persists for the lifetime of the module. In test environments,
+any call to `markDevtoolsActive()` MUST be paired with a `release()` call
+inside a `try/finally` block. Failing to do so leaves `devtoolsActive = true`
+for all subsequent tests, causing false positives in devtools-conditional
+rendering paths (e.g. `data-jr-key` wrapper spans).
+
+```ts
+const release = markDevtoolsActive();
+try {
+	// test code
+} finally {
+	release();
+}
+```
+
+## Example
+
+```ts
+const { registry, handlers } = defineRegistry(catalog, { components, actions });
+const resolvedHandlers = handlers(
+	() => undefined,
+	() => ({}),
+);
+const node = renderSpec(spec, store, registry, {
+	send: actor.send.bind(actor),
+	handlers: resolvedHandlers,
+});
+if (node) container.appendChild(node);
+```

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

@@ -0,0 +1,23 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / ComponentContext
+
+# Interface: ComponentContext\<C, K\>
+
+Defined in: `@xmachines/json-render-dom`
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Properties
+
+| Property                                  | Type                                          | Description                                                                      | Defined in |
+| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | ---------- |
+| <a id="property-bindings"></a> `bindings` | `Record`\<`string`, `string`\> \| `undefined` | Two-way binding paths resolved from `$bindState` / `$bindItem` prop expressions. | -          |
+| <a id="property-children"></a> `children` | `Node`[]                                      | Rendered child nodes from the spec's `children` list.                            | -          |
+| <a id="property-ctx"></a> `ctx`           | [`DomRenderContext`](DomRenderContext.md)     | Low-level render context.                                                        | -          |
+| <a id="property-emit"></a> `emit`         | (`event`) => `void`                           | Dispatch a named event defined in the spec's `on` map.                           | -          |
+| <a id="property-on"></a> `on`             | (`event`) => [`EventHandle`](EventHandle.md)  | Get an `EventHandle` for a named event from the spec's `on` map.                 | -          |
+| <a id="property-props"></a> `props`       | `InferComponentProps`\<`C`, `K`\>             | Catalog-typed, store-resolved props for this component.                          | -          |

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

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / CreatePlayUIOptions
+
+# Interface: CreatePlayUIOptions
+
+Defined in: [packages/play-dom/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/types.ts#L67)
+
+Options for `createPlayUI()` — the batteries-included DOM factory.
+
+Extends [UIProviderOptions](UIProviderOptions.md), which contributes `functions`,
+`directives`, `validationFunctions`, `navigate`, and `onRenderError`. All
+are closed over at factory creation time and forwarded into `PlayRenderer`
+on every `mount()` call.
+
+Parallel to `PlayUIProvider`'s props in the framework renderers.
+
+## See
+
+createPlayUI
+
+## Extends
+
+- [`UIProviderOptions`](UIProviderOptions.md)
+
+## Properties
+
+| Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Inherited from                                                                                                         | Defined in                                                                                                                       |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                     | [`UIProviderOptions`](UIProviderOptions.md).[`directives`](UIProviderOptions.md#property-directives)                   | -                                                                                                                                |
+| <a id="property-fallback"></a> `fallback?`                       | `HTMLElement` \| `null`                                                                                   | Optional fallback element shown when `currentView` is `null` on **initial mount** only. The fallback is appended immediately after `mount()` if the container is empty at that moment (i.e. the actor's initial view is `null`). **Limitation:** If the actor's view transitions to `null` after mount, the container will be cleared but this fallback will NOT be re-appended. For dynamic fallback behavior (null view after non-null), use `PlayRenderer` directly and wrap the `actor.currentView` signal to inject fallback content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                      | [packages/play-dom/src/types.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/types.ts#L79) |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | -                                                                                                                                |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                  | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | -                                                                                                                                |
+| <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`UIProviderOptions`](UIProviderOptions.md).[`onConfirm`](UIProviderOptions.md#property-onconfirm)                     | -                                                                                                                                |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Unified error handler for component render errors and action handler rejections. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Invoked for three distinct error classes: - `(error, elementType)` — when a component renderer throws synchronously during `renderSpec` - `(error, actionName)` — when an action handler rejects during `emit()` (on-event path) - `(error, actionName)` — when an action handler rejects during a `watch` binding callback When provided, suppresses the `console.error` fallback for all three error types. Forwarded into `renderSpec` as the `onRenderError` parameter and into `DomRenderContext.onRenderError` so both `emit()` and `watch` handlers route their errors through the same channel as component render errors. **Example** `renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, });`                                                                                                                                                                                                                                               | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | -                                                                                                                                |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions for inline field validation. Each function receives `(value, args?)` and returns `true` (valid) or `false` (invalid). Functions are available to component implementations via `ctx.ctx.validationFunctions` and should be passed as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Mirrors `customFunctions` in `ValidationProvider` from the framework renderers. The DOM renderer has no automatic `ValidationProvider` tree — validation must be invoked explicitly by component implementations. **Example** `import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { 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 };` | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | -                                                                                                                                |

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

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / DefineRegistryResult
+
+# Interface: DefineRegistryResult
+
+Defined in: `@xmachines/json-render-dom`
+
+Result returned by `defineRegistry`.
+
+Matches `DefineRegistryResult` from @xmachines/json-render-react, /solid, /svelte, /vue.
+
+## Properties
+
+| Property                                            | Type                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                           | Defined in |
+| --------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-executeaction"></a> `executeAction` | (`actionName`, `params`, `setState`, `state?`) => `Promise`\<`void`\> | Execute a named action by name, with optional params. Mirrors `executeAction` on `DefineRegistryResult` from @xmachines/json-render-react, /solid, /vue, /svelte. Useful for programmatically triggering actions outside of the emit/on flow.                                                                                                                                         | -          |
+| <a id="property-handlers"></a> `handlers`           | (`getSetState`, `getState`) => `Record`\<`string`, `ActionHandler`\>  | Create ActionProvider-compatible handlers. Accepts getter functions (called lazily at action-invocation time) so handlers always see the latest setState and state snapshot — matching the pattern from the framework renderers. Host renderers typically wire these from their state store. Pass `() => undefined, () => ({})` only in tests or when state management is not needed. | -          |
+| <a id="property-registry"></a> `registry`           | [`DomRegistry`](../type-aliases/DomRegistry.md)                       | The built `DomRegistry`, ready to pass to `renderSpec`.                                                                                                                                                                                                                                                                                                                               | -          |

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

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / DomRenderContext
+
+# Interface: DomRenderContext
+
+Defined in: `@xmachines/json-render-dom`
+
+Low-level render context passed to each `DomComponentRenderer`.
+
+## Properties
+
+| Property                                                         | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Defined in |
+| ---------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-directives"></a> `directives?`                   | `DirectiveRegistry`                                           | Custom directive registry, converted from `UIProviderOptions.directives` (a `DirectiveDefinition[]`) once per render pass and forwarded to `PropResolutionContext.directives`. Components that resolve prop sub-values themselves (via `resolvePropValue` from `@xmachines/json-render-core`) should include this in their resolution context so custom `$`-prefixed dynamic values keep working inside those values. Mirrors the directives context from the framework renderers (`useDirectives` / `DirectivesContextProvider` / `DIRECTIVES_KEY`). | -          |
+| <a id="property-elementbindings"></a> `elementBindings?`         | `Record`\<`string`, `string`\>                                | Pre-computed two-way binding paths for this element's props.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -          |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                      | Optional map of named compute functions, forwarded to PropResolutionContext. Enables { $computed: "funcName", args: {...} } prop expressions to resolve. Mirrors the `functions` prop from framework renderer providers.                                                                                                                                                                                                                                                                                                                              | -          |
+| <a id="property-handlers"></a> `handlers`                        | `Record`\<`string`, `ActionHandler`\>                         | Map of json-render catalog action names → async ActionHandler functions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -          |
+| <a id="property-loading"></a> `loading?`                         | `boolean`                                                     | When true, indicates the spec is still streaming (e.g. from an AI provider). Component implementations can use this to show skeleton/loading states. When loading=true, missing-child warnings are suppressed. Mirrors the `loading` prop from framework renderer providers.                                                                                                                                                                                                                                                                          | -          |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                            | Navigation function forwarded from `UIProviderOptions`. Called when an action binding has `onSuccess: { navigate: "/path" }`. Mirrors the `navigate` prop in `ActionProvider` from framework renderers.                                                                                                                                                                                                                                                                                                                                               | -          |
+| <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)         | Confirmation hook forwarded from `UIProviderOptions.onConfirm`. Consulted by `emit()` before executing an action binding that declares `confirm`. When absent, confirm-gated actions are skipped with a `console.warn` instead of executing unconfirmed.                                                                                                                                                                                                                                                                                              | -          |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | Error handler forwarded from `UIProviderOptions.onRenderError`. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Called by `emit()` when an action handler rejects, with `(error, actionName)`. Also called by `renderSpec` when a component renderer throws, with `(error, elementType)`. When absent, both fall back to `console.error`. Component implementations may call this directly via `ctx.ctx.onRenderError` to surface errors through the application's central error channel.                                      | -          |
+| <a id="property-renderchildren"></a> `renderChildren`            | (`keys`) => `Node`[]                                          | Render a list of child element keys into DOM nodes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -          |
+| <a id="property-repeatbasepath"></a> `repeatBasePath?`           | `string`                                                      | Absolute JSON Pointer path to the current repeat item (e.g. "/todos/0"). Mirrors `repeatBasePath` in `PropResolutionContext`.                                                                                                                                                                                                                                                                                                                                                                                                                         | -          |
+| <a id="property-repeatindex"></a> `repeatIndex?`                 | `number`                                                      | Current repeat array index when inside a repeat scope. Mirrors `repeatIndex` in `PropResolutionContext`.                                                                                                                                                                                                                                                                                                                                                                                                                                              | -          |
+| <a id="property-repeatitem"></a> `repeatItem?`                   | `unknown`                                                     | Current repeat item when inside a repeat scope. Mirrors `repeatItem` in `@xmachines/json-render-core`'s `PropResolutionContext`.                                                                                                                                                                                                                                                                                                                                                                                                                      | -          |
+| <a id="property-send"></a> `send`                                | (`event`) => `void`                                           | Dispatch an event (e.g. to an XState actor).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -          |
+| <a id="property-spec"></a> `spec`                                | `Spec`                                                        | Full spec tree for this render pass.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -          |
+| <a id="property-store"></a> `store`                              | `StateStore`                                                  | Live state store bound to `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | -          |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>         | Custom validation functions available to `runValidation` / `runValidationCheck`. Each function receives `(value, args?)` and returns a boolean. Mirrors `customFunctions` in `ValidationProvider` from framework renderers. Components that perform inline validation (e.g. form fields) should read this from `ctx.ctx.validationFunctions` and pass it as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`.                                                                                           | -          |

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

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / EventHandle
+
+# Interface: EventHandle
+
+Defined in: `@xmachines/json-render-dom`
+
+Handle returned by `ComponentContext.on(eventName)`.
+
+## Properties
+
+| Property                                                          | Type         | Description                                                              | Defined in |
+| ----------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ---------- |
+| <a id="property-bound"></a> `bound`                               | `boolean`    | `true` if an `on` binding exists for this event name; `false` otherwise. | -          |
+| <a id="property-emit"></a> `emit`                                 | () => `void` | Fire the bound action, resolving params from the current state store.    | -          |
+| <a id="property-shouldpreventdefault"></a> `shouldPreventDefault` | `boolean`    | Whether any binding for this event has `preventDefault: true`.           | -          |

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

@@ -0,0 +1,18 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / MountOptions
+
+# Interface: MountOptions
+
+Defined in: [packages/play-dom/src/create-play-ui.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/create-play-ui.ts#L48)
+
+Per-mount options passed to the `MountFn` returned by `createPlayUI`.
+
+These override or supplement the factory-level options on a per-actor/container
+basis. Factory-level options (`functions`, `validationFunctions`, `navigate`,
+`onRenderError`, `fallback`) are set once when calling `createPlayUI`.
+
+## Properties
+
+| Property                                 | Type         | Description                                                                                                                                           | Defined in                                                                                                                                         |
+| ---------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-loading"></a> `loading?` | `boolean`    | When `true`, suppresses missing-child warnings during streaming spec ingestion and exposes `ctx.ctx.loading` to component implementations.            | [packages/play-dom/src/create-play-ui.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/create-play-ui.ts#L59) |
+| <a id="property-store"></a> `store?`     | `StateStore` | Optional external `StateStore` (controlled mode). When omitted, a fresh `@xstate/store` atom is created per view transition seeded from `spec.state`. | [packages/play-dom/src/create-play-ui.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/create-play-ui.ts#L54) |

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

@@ -0,0 +1,30 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / PlayDomOptions
+
+# Interface: PlayDomOptions
+
+Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/types.ts#L23)
+
+Options for `PlayRenderer`.
+
+Extends [UIProviderOptions](UIProviderOptions.md), which contributes `functions`,
+`directives`, `validationFunctions`, `navigate`, and `onRenderError`. All
+are forwarded into `DomRenderContext` on every render pass and are readable
+by component implementations via `ctx.ctx.*`.
+
+## Extends
+
+- [`UIProviderOptions`](UIProviderOptions.md)
+
+## Properties
+
+| Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Inherited from                                                                                                         | Defined in                                                                                                                       |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                     | [`UIProviderOptions`](UIProviderOptions.md).[`directives`](UIProviderOptions.md#property-directives)                   | -                                                                                                                                |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`UIProviderOptions`](UIProviderOptions.md).[`functions`](UIProviderOptions.md#property-functions)                     | -                                                                                                                                |
+| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                 | When `true`, indicates the spec is still streaming (e.g. from an AI provider). Forwarded to `renderSpec` so component implementations can read `ctx.ctx.loading` to render skeleton states. Also suppresses missing-child warnings during stream ingestion, since referenced elements may not yet have arrived in the incremental spec. Mirrors the `loading` prop from framework renderer providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                      | [packages/play-dom/src/types.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/types.ts#L52) |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                  | [`UIProviderOptions`](UIProviderOptions.md).[`navigate`](UIProviderOptions.md#property-navigate)                       | -                                                                                                                                |
+| <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`UIProviderOptions`](UIProviderOptions.md).[`onConfirm`](UIProviderOptions.md#property-onconfirm)                     | -                                                                                                                                |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Unified error handler for component render errors and action handler rejections. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Invoked for three distinct error classes: - `(error, elementType)` — when a component renderer throws synchronously during `renderSpec` - `(error, actionName)` — when an action handler rejects during `emit()` (on-event path) - `(error, actionName)` — when an action handler rejects during a `watch` binding callback When provided, suppresses the `console.error` fallback for all three error types. Forwarded into `renderSpec` as the `onRenderError` parameter and into `DomRenderContext.onRenderError` so both `emit()` and `watch` handlers route their errors through the same channel as component render errors. **Example** `renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, });`                                                                                                                                                                                                                                               | [`UIProviderOptions`](UIProviderOptions.md).[`onRenderError`](UIProviderOptions.md#property-onrendererror)             | -                                                                                                                                |
+| <a id="property-registryresult"></a> `registryResult?`           | [`DefineRegistryResult`](DefineRegistryResult.md)                                                         | The result from `defineRegistry` — provides both the registry and the handlers factory. When provided, `PlayRenderer` wires `setState` and `getState` from the @xstate/store-backed `StateStore` into the handlers factory automatically. This is the preferred approach as it ensures actions always receive live `setState` and `state` bound to the current store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                      | [packages/play-dom/src/types.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/types.ts#L31) |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | Optional external StateStore (e.g. from `xstateStoreStateStore` in @xmachines/json-render-xstate). When provided, `PlayRenderer` operates in controlled mode — `spec.state` is ignored and this store is the single source of truth for UI state (form values, etc.). When omitted, a fresh `@xstate/store` atom is created internally per view transition, seeded from `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                      | [packages/play-dom/src/types.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/types.ts#L41) |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions for inline field validation. Each function receives `(value, args?)` and returns `true` (valid) or `false` (invalid). Functions are available to component implementations via `ctx.ctx.validationFunctions` and should be passed as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Mirrors `customFunctions` in `ValidationProvider` from the framework renderers. The DOM renderer has no automatic `ValidationProvider` tree — validation must be invoked explicitly by component implementations. **Example** `import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { 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 };` | [`UIProviderOptions`](UIProviderOptions.md).[`validationFunctions`](UIProviderOptions.md#property-validationfunctions) | -                                                                                                                                |

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

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / RenderSpecOptions
+
+# Interface: RenderSpecOptions
+
+Defined in: `@xmachines/json-render-dom`
+
+Named options for [renderSpec](../functions/renderSpec.md).
+
+All fields are optional — `send` defaults to a no-op and `handlers` to an
+empty map, so `renderSpec(spec, store, registry)` renders a static tree.
+
+## Properties
+
+| Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Defined in |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language. Converted to a `DirectiveRegistry` once per `renderSpec` call and forwarded to `PropResolutionContext.directives`, matching the framework renderers' `directives` prop (@json-render 0.19). Built-in expressions always take precedence over custom directives.                                                                                                                                                                                                                                                | -          |
+| <a id="property-fallback"></a> `fallback?`                       | [`DomComponentRenderer`](../type-aliases/DomComponentRenderer.md)                                         | Renderer called when `registry` has no entry for an element's `type` (GAP-04). If absent, unknown types render as `null`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -          |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Map of named compute functions forwarded to `PropResolutionContext` (GAP-03). Enables `{ $computed: "fn", args }` prop expressions to resolve. When absent, `$computed` expressions return `undefined` (no throw).                                                                                                                                                                                                                                                                                                                                                                                                    | -          |
+| <a id="property-handlers"></a> `handlers?`                       | `Record`\<`string`, `ActionHandler`\>                                                                     | Map of catalog action names → async `ActionHandler` functions, consumed by `defineRegistry`'s `emit()`/`watch` dispatch. Defaults to `{}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -          |
+| <a id="property-loading"></a> `loading?`                         | `boolean`                                                                                                 | Flag indicating the spec is still streaming (GAP-06). When `true`, components can read `ctx.loading` to render skeleton states, and missing-child warnings (GAP-07) are suppressed since referenced elements may not yet have arrived in the incremental spec.                                                                                                                                                                                                                                                                                                                                                        | -          |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Navigation callback forwarded to `DomRenderContext.navigate`. Invoked automatically by `defineRegistry`'s `emit()` when an action binding resolves with `onSuccess: { navigate: "/path" }`. Also readable by component implementations via `ctx.navigate`.                                                                                                                                                                                                                                                                                                                                                            | -          |
+| <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook forwarded to `DomRenderContext.onConfirm`. Consulted by `defineRegistry`'s `emit()` before executing an action binding that declares `confirm`. Without it, confirm-gated actions are skipped with a `console.warn` (never executed unconfirmed).                                                                                                                                                                                                                                                                                                                                                   | -          |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Callback matching `RenderErrorHandler = (error, name)`. Invoked for three distinct error classes: - `(error, elementType)` when a component renderer throws (GAP-08) - `(error, actionName)` when an action handler rejects during `emit()` - `(error, actionName)` when an action handler rejects in a `watch` binding If absent, all three fall back to `console.error`. Forwarded into `DomRenderContext.onRenderError` so `emit()` and `watch` handlers route errors through the same channel as component render errors.                                                                                         | -          |
+| <a id="property-onwatchsetup"></a> `onWatchSetup?`               | (`cleanup`) => `void` \| (() => `void`)                                                                   | Callback invoked with each watch subscription cleanup function (GAP-02). When an element declares `watch`, the renderer sets up a store subscription and passes its unsubscribe function to this callback. Host renderers collect these to call on teardown. When absent, `watch` bindings are not wired. May return a replacement cleanup: when the caller wraps the supplied cleanup (e.g. to drop it from its own collection when invoked), the incremental renderer registers the returned wrapper so an unmount-driven release also runs the caller's bookkeeping. Returning nothing keeps the supplied cleanup. | -          |
+| <a id="property-send"></a> `send?`                               | (`event`) => `void`                                                                                       | Dispatcher for interaction events (e.g. `actor.send`), exposed to component implementations via `ctx.send`. Defaults to a no-op.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -          |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions forwarded to `DomRenderContext.validationFunctions`. Components pass these as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Has no effect on prop resolution.                                                                                                                                                                                                                                                                                                                                                                           | -          |

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

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / UIProviderOptions
+
+# Interface: UIProviderOptions
+
+Defined in: `@xmachines/json-render-dom`
+
+Shared UI-provider options — the configurable rendering behaviours that sit
+above the core actor/registry wiring.
+
+These fields mirror the forwarded props on `JSONUIProvider` /
+`JsonUIProvider` across @xmachines/json-render-react, /vue, /solid, /svelte.
+Grouping them here lets host renderers extend a single source of truth
+without repeating field declarations.
+
+All four fields are threaded into `DomRenderContext` on every render pass
+and are available to component implementations via `ctx.ctx.*`.
+
+## Extended by
+
+- [`PlayDomOptions`](PlayDomOptions.md)
+- [`CreatePlayUIOptions`](CreatePlayUIOptions.md)
+
+## Properties
+
+| Property                                                         | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Defined in |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-directives"></a> `directives?`                   | `DirectiveDefinition`\<`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>\>[] | Custom directives — user-defined `$`-prefixed dynamic values that extend the spec expression language (e.g. `{ $format: "currency", value: ... }`). Each entry is a `DirectiveDefinition` built with `defineDirective` from `@xmachines/json-render-core`. The array is converted to a `DirectiveRegistry` once per render pass and forwarded to `resolveElementProps` via `PropResolutionContext.directives`. Built-in expressions (`$state`, `$cond`, etc.) always take precedence over custom directives. Mirrors the `directives` prop on `JSONUIProvider` / `JsonUIProvider` introduced in **Json-render** 0.19. **Example** `import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] });`                     | -          |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                  | Named compute functions for `{ $computed: "name", args: {...} }` prop expressions. Each function receives the resolved `args` object and returns the computed value. Forwarded directly to `resolveElementProps` via `PropResolutionContext.functions`, matching the `FunctionsContext` provider in the framework renderers. Without this option, `$computed` expressions resolve to `undefined` (no throw). **Example** `renderSpec(spec, store, registry, { functions: { fullName: (args) => `${args.first} ${args.last}`, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, });` Mirrors the `functions` prop on `JSONUIProvider` / `JsonUIProvider`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -          |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                        | Programmatic navigation function. Called automatically when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Mirrors the `navigate` prop in `ActionProvider` from the framework renderers, where it is captured in the `execute()` closure. Also available to component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding. **Example** `import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate });` Spec binding that triggers navigation: `{ "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } }`                                                                                                                                                                                                                                                                                                                                                                                                                  | -          |
+| <a id="property-onconfirm"></a> `onConfirm?`                     | [`ConfirmHandler`](../type-aliases/ConfirmHandler.md)                                                     | Confirmation hook for actions that declare `confirm` in their binding. Consulted by `emit()` before executing a confirm-gated action. Return (or resolve) `true` to execute, `false` to skip. Without this handler, confirm-gated actions are skipped with a `console.warn` — they never execute unconfirmed. See [ConfirmHandler](../type-aliases/ConfirmHandler.md) for the full contract. This is the headless equivalent of the `pendingConfirmation` / `confirmAction()` / `cancelAction()` flow in the framework adapters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | -          |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                             | Unified error handler for component render errors and action handler rejections. Matches `RenderErrorHandler = (error: unknown, name: string) => void`. Invoked for three distinct error classes: - `(error, elementType)` — when a component renderer throws synchronously during `renderSpec` - `(error, actionName)` — when an action handler rejects during `emit()` (on-event path) - `(error, actionName)` — when an action handler rejects during a `watch` binding callback When provided, suppresses the `console.error` fallback for all three error types. Forwarded into `renderSpec` as the `onRenderError` parameter and into `DomRenderContext.onRenderError` so both `emit()` and `watch` handlers route their errors through the same channel as component render errors. **Example** `renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, });`                                                                                                                                                                                                                                               | -          |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                     | Custom validation functions for inline field validation. Each function receives `(value, args?)` and returns `true` (valid) or `false` (invalid). Functions are available to component implementations via `ctx.ctx.validationFunctions` and should be passed as `customFunctions` to `runValidationCheck` / `runValidation` from `@xmachines/json-render-core`. Mirrors `customFunctions` in `ValidationProvider` from the framework renderers. The DOM renderer has no automatic `ValidationProvider` tree — validation must be invoked explicitly by component implementations. **Example** `import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { 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 };` | -          |

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

@@ -0,0 +1,46 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / ActionFn
+
+# Type Alias: ActionFn\<C, K\>
+
+```ts
+type ActionFn<C, K> = (params, setState, state) => Promise<void>;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+Catalog-typed action function — mirrors `ActionFn<C, K>` from @xmachines/json-render-react, /solid, /vue.
+
+- `params` is typed to the exact param schema defined in the catalog, or `undefined` if the
+  spec provided no params. Guard against undefined before accessing params.
+- `setState` writes to the backing local state store. Use it to update ephemeral
+  UI state (e.g. form field values, error messages) from within an action handler.
+- `state` is a snapshot of the current state model at the time the action was invoked.
+
+## Type Parameters
+
+| Type Parameter                                   |
+| ------------------------------------------------ |
+| `C` _extends_ `Catalog`                          |
+| `K` _extends_ keyof `InferCatalogActions`\<`C`\> |
+
+## Parameters
+
+| Parameter  | Type                                           |
+| ---------- | ---------------------------------------------- |
+| `params`   | `InferActionParams`\<`C`, `K`\> \| `undefined` |
+| `setState` | [`SetState`](SetState.md)                      |
+| `state`    | `StateModel`                                   |
+
+## Returns
+
+`Promise`\<`void`\>
+
+## Example
+
+```ts
+login: async (params, setState, state) => {
+	if (!params) return;
+	setState((prev) => ({ ...prev, loading: true }));
+	await actor.send({ type: "auth.login", username: params.username });
+};
+```

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

@@ -0,0 +1,18 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / Actions
+
+# Type Alias: Actions\<C\>
+
+```ts
+type Actions<C> = { [K in keyof InferCatalogActions<C>]: ActionFn<C, K> };
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+Map of catalog-typed action handler functions.
+Each key is a catalog action name; each value is an `ActionFn<C, K>` for that action.
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |