@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -6,12 +6,13 @@
 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/v2.0.0-alpha.1/packages/play-dom/src/create-renderer.ts#L84)
+Defined in: [packages/play-dom/src/create-renderer.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-renderer.ts#L88)
 
-Create a reusable DOM renderer factory from a catalog and component map.
+Creates a DOM renderer factory from a catalog and a component map. You can use
+the factory more than one time.
 
-Returns a `mount(actor, container, options?)` function that wires up the
-PlayRenderer in one call and returns a `disconnect` cleanup function.
+It returns a `mount(actor, container, options?)` function. That function connects
+the PlayRenderer in one call, and it returns a `disconnect` cleanup function.
 
 ## Type Parameters
 
@@ -21,24 +22,27 @@ PlayRenderer in one call and returns a `disconnect` cleanup function.
 
 ## 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.       |
+| Parameter      | Type                                                               | Description                                                                            |
+| -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `catalog`      | `C`                                                                | The json-render Catalog. It describes the schema of each component and of each action. |
+| `componentMap` | [`ComponentRegistry`](../type-aliases/ComponentRegistry.md)\<`C`\> | The component implementations, with the catalog component name as the key.             |
 
 ## Returns
 
-A `mount` function that accepts `(actor, container, options?)` and returns `disconnect`.
+A `mount` function. It accepts `(actor, container, options?)`, and it 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`.
+`createRenderer` manages `registryResult` internally. It calls `defineRegistry`
+one time, and it uses that result in every `mount()` call. Therefore the options
+type of `mount` holds no `registryResult`: `createRenderer` always gives it, and
+you cannot replace it.
+
+Two situations need a different function. In the first, your code calls
+`registryResult.executeAction()` itself, outside the emit and on flow. In the
+second, you give more provider options, such as `navigate`, `onRenderError`, or
+`functions`. Use `createPlayUI`, which accepts the complete
+`CreatePlayUIOptions`. You can also use `defineRegistry` with `PlayRenderer`
+directly.

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

@@ -0,0 +1,22 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / createValidationRegistry
+
+# Function: createValidationRegistry()
+
+```ts
+function createValidationRegistry(store, customFunctions?): ValidationRegistry;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+Create a validation registry bound to `store`.
+
+## Parameters
+
+| Parameter          | Type                                       | Description                                                                                                                                       |
+| ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `store`            | `StateStore`                               | Live state store; field values are read from its current snapshot on every `validate` call, so a validation sees writes made in the same handler. |
+| `customFunctions?` | `Record`\<`string`, `ValidationFunction`\> | Catalog validation functions, keyed by check type.                                                                                                |
+
+## Returns
+
+[`ValidationRegistry`](../interfaces/ValidationRegistry.md)

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

@@ -3,7 +3,7 @@
 # Function: defineRegistry()
 
 ```ts
-function defineRegistry<C>(_catalog, options): DefineRegistryResult;
+function defineRegistry<C>(catalog, options): DefineRegistryResult;
 ```
 
 Defined in: `@xmachines/json-render-dom`
@@ -16,10 +16,10 @@ Defined in: `@xmachines/json-render-dom`
 
 ## Parameters
 
-| Parameter  | Type                                                                       |
-| ---------- | -------------------------------------------------------------------------- |
-| `_catalog` | `C`                                                                        |
-| `options`  | [`DefineRegistryOptions`](../type-aliases/DefineRegistryOptions.md)\<`C`\> |
+| Parameter | Type                                                                       |
+| --------- | -------------------------------------------------------------------------- |
+| `catalog` | `C`                                                                        |
+| `options` | [`DefineRegistryOptions`](../type-aliases/DefineRegistryOptions.md)\<`C`\> |
 
 ## Returns
 

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

@@ -13,11 +13,12 @@ Defined in: `@xmachines/json-render-dom`
 
 ## 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.                          | -          |
+| 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 (the default slot).                                                                                                                | -          |
+| <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.                                                                                                                                 | -          |
+| <a id="property-slots"></a> `slots?`      | `Record`\<`string`, `Node`[]\>                | Rendered nodes per named slot from the spec's `slots` map, or `undefined` when the element fills no named slot. Mirrors `slots` in @xmachines/json-render-react's ComponentRenderProps. | -          |

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

@@ -2,16 +2,16 @@
 
 # Interface: CreatePlayUIOptions
 
-Defined in: [packages/play-dom/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/types.ts#L67)
+Defined in: [packages/play-dom/src/types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L69)
 
-Options for `createPlayUI()` — the batteries-included DOM factory.
+The options of `createPlayUI()`, the complete 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.
+This type extends [UIProviderOptions](UIProviderOptions.md), which gives `functions`,
+`directives`, `validationFunctions`, `navigate`, and `onRenderError`. The factory
+holds all of them from the moment of its creation, and it gives them to
+`PlayRenderer` on every `mount()` call.
 
-Parallel to `PlayUIProvider`'s props in the framework renderers.
+This type is parallel to the props of `PlayUIProvider` in the framework renderers.
 
 ## See
 
@@ -23,12 +23,12 @@ createPlayUI
 
 ## 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/v2.0.0-alpha.1/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) | -                                                                                                                                        |
+| 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`                                                                                   | The optional fallback element. The factory shows it when `currentView` is `null` on the **first mount** only. The factory appends the fallback directly after `mount()`, when the container is empty at that moment, which means that the first view of the actor is `null`. **Limitation:** when the view of the actor becomes `null` after the mount, the renderer clears the container, and it does NOT append this fallback again. For a dynamic fallback, which follows a null view after a view that was not null, use `PlayRenderer` directly and wrap the `actor.currentView` signal to add the fallback content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                                                                                                      | [packages/play-dom/src/types.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L82) |
+| <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/DomRenderContext.md

@@ -19,10 +19,12 @@ Low-level render context passed to each `DomComponentRenderer`.
 | <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-renderslot"></a> `renderSlot`                    | (`slotName`) => `Node`[]                                      | Render the children the element placed in a named slot (`element.slots`). Returns `[]` for a slot the element does not fill. Slot children render with the enclosing repeat scope, not once per item of this element's own `repeat`.                                                                                                                                                                                                                                                                                                                  | -          |
 | <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-validation"></a> `validation`                    | [`ValidationRegistry`](ValidationRegistry.md)                 | Field-validation registry for this tree. Components register their field's `ValidationConfig` here during render (`registerField`) and validate on change/blur (`validate`); the `validateForm` built-in validates every registered field. Mirrors the framework renderers' ValidationProvider.                                                                                                                                                                                                                                                       | -          |
 | <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/FieldValidationState.md

@@ -0,0 +1,16 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / FieldValidationState
+
+# Interface: FieldValidationState
+
+Defined in: `@xmachines/json-render-dom`
+
+Per-field validation state. Mirrors `FieldValidationState` in
+@xmachines/json-render-react's ValidationProvider.
+
+## Properties
+
+| Property                                    | Type                         | Description                                                 | Defined in |
+| ------------------------------------------- | ---------------------------- | ----------------------------------------------------------- | ---------- |
+| <a id="property-result"></a> `result`       | `ValidationResult` \| `null` | Result of the last validation, or `null` when only touched. | -          |
+| <a id="property-touched"></a> `touched`     | `boolean`                    | The field has been interacted with.                         | -          |
+| <a id="property-validated"></a> `validated` | `boolean`                    | The field has been validated at least once.                 | -          |

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

@@ -2,17 +2,17 @@
 
 # Interface: MountOptions
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/create-play-ui.ts#L48)
+Defined in: [packages/play-dom/src/create-play-ui.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L49)
 
-Per-mount options passed to the `MountFn` returned by `createPlayUI`.
+The mount options of the `MountFn` that `createPlayUI` returns.
 
-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`.
+They replace or complete the factory options, for one actor and one container.
+The `createPlayUI` call sets the factory options (`functions`,
+`validationFunctions`, `navigate`, `onRenderError`, and `fallback`) one time.
 
 ## 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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/packages/play-dom/src/create-play-ui.ts#L54) |
+| Property                                 | Type         | Description                                                                                                                                                                              | Defined in                                                                                                                                         |
+| ---------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-loading"></a> `loading?` | `boolean`    | With the value `true`, the renderer stops each warning about an absent child during the ingestion of a streaming spec. It also gives `ctx.ctx.loading` to each component implementation. | [packages/play-dom/src/create-play-ui.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L61) |
+| <a id="property-store"></a> `store?`     | `StateStore` | The optional external `StateStore`, which is the controlled mode. Without it, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.   | [packages/play-dom/src/create-play-ui.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L55) |

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

@@ -2,14 +2,14 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/types.ts#L23)
+Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L23)
 
-Options for `PlayRenderer`.
+The options of `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.*`.
+This type extends [UIProviderOptions](UIProviderOptions.md), which gives `functions`,
+`directives`, `validationFunctions`, `navigate`, and `onRenderError`. Each render
+pass puts all of them into `DomRenderContext`, and a component implementation
+reads them at `ctx.ctx.*`.
 
 ## Extends
 
@@ -17,14 +17,14 @@ by component implementations via `ctx.ctx.*`.
 
 ## 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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/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) | -                                                                                                                                        |
+| 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`                                                                                                 | With the value `true`, the spec is still streaming, for example from an AI provider. The renderer gives the flag to `renderSpec`. A component implementation therefore reads `ctx.ctx.loading`, and it can render a skeleton state. The flag also stops each warning about an absent child during the ingestion of the stream, because an element of a reference can still be absent from the incremental spec. This option matches the `loading` prop of the framework renderer providers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -                                                                                                                      | [packages/play-dom/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L54) |
+| <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 of `defineRegistry`. It gives the registry and the factory of the handlers. With this option, `PlayRenderer` connects `setState` and `getState` of the `StateStore` on @xstate/store to the factory of the handlers for you. This is the preferred way, because each action then always receives a live `setState` and a live `state` on the current store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                      | [packages/play-dom/src/types.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L32) |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                              | The optional external StateStore, for example from `xstateStoreStateStore` in @xmachines/json-render-xstate. With this option, `PlayRenderer` works in the controlled mode: it ignores `spec.state`, and this store is the single source of truth of the UI state, such as a form value. Without this option, the renderer makes a new `@xstate/store` atom for each view transition, with the values of `spec.state`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                      | [packages/play-dom/src/types.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/types.ts#L42) |
+| <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

@@ -21,6 +21,8 @@ empty map, so `renderSpec(spec, store, registry)` renders a static tree.
 | <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-onvalidationsetup"></a> `onValidationSetup?`     | (`cleanup`) => `void`                                                                                     | Called with an unregister callback for every field an element registers through `ctx.validation.registerField`, so a host can release the registrations of an element instance when it unmounts. Mirrors `onWatchSetup`.                                                                                                                                                                                                                                                                                                                                                                                              | -          |
 | <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-validation"></a> `validation?`                   | [`ValidationRegistry`](ValidationRegistry.md)                                                             | Field-validation registry shared by the whole tree, exposed to components as `ctx.validation` and used by the `validateForm` built-in. One is created per `renderSpec` call when omitted; a host that re-renders (e.g. the incremental renderer) must create one for its lifetime and pass it on every pass so registrations survive.                                                                                                                                                                                                                                                                                 | -          |
 | <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/ValidationRegistry.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / ValidationRegistry
+
+# Interface: ValidationRegistry
+
+Defined in: `@xmachines/json-render-dom`
+
+Registry of validated fields for one rendered tree.
+
+## Properties
+
+| Property                                                | Modifier   | Type                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in |
+| ------------------------------------------------------- | ---------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-clear"></a> `clear`                     | `public`   | (`path`) => `void`                                                      | Forget a field's recorded state; the registration itself survives.                                                                                                                                                                                                                                                                                                                                                     | -          |
+| <a id="property-customfunctions"></a> `customFunctions` | `readonly` | `Record`\<`string`, `ValidationFunction`\>                              | Custom validation functions available to every check.                                                                                                                                                                                                                                                                                                                                                                  | -          |
+| <a id="property-fieldstates"></a> `fieldStates`         | `readonly` | `Record`\<`string`, [`FieldValidationState`](FieldValidationState.md)\> | Validation state by field state path.                                                                                                                                                                                                                                                                                                                                                                                  | -          |
+| <a id="property-registerfield"></a> `registerField`     | `public`   | (`path`, `config`) => `void`                                            | Register (or update) a field's validation config. Called by component implementations during render, normally via `ctx.validation`. Registrations are reference-counted per path: two elements bound to the same state path each hold one, so one of them going away does not un-validate the other.                                                                                                                   | -          |
+| <a id="property-releasefield"></a> `releaseField`       | `public`   | (`path`) => `void`                                                      | Drop one reference to a field's registration, keeping its recorded state. The registration itself goes away once the last reference is released. This is what the render context's per-element cleanup calls: an element instance releases its registrations when it unmounts or before it re-renders, and `fieldStates` survives — matching the framework ValidationProvider, whose field states outlive a re-render. | -          |
+| <a id="property-touch"></a> `touch`                     | `public`   | (`path`) => `void`                                                      | Mark a field as interacted with, without validating it.                                                                                                                                                                                                                                                                                                                                                                | -          |
+| <a id="property-unregisterfield"></a> `unregisterField` | `public`   | (`path`) => `void`                                                      | Drop a field's registration entirely, references and recorded state.                                                                                                                                                                                                                                                                                                                                                   | -          |
+| <a id="property-validate"></a> `validate`               | `public`   | (`path`, `config?`) => `ValidationResult`                               | Validate one field against the live store snapshot and record the result. Uses the field's registered config unless one is passed explicitly.                                                                                                                                                                                                                                                                          | -          |
+| <a id="property-validateall"></a> `validateAll`         | `public`   | () => `boolean`                                                         | Validate every registered field. Returns true when all are valid.                                                                                                                                                                                                                                                                                                                                                      | -          |

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

@@ -112,3 +112,13 @@ props: P;
 ```
 
 Defined in: `@xmachines/json-render-dom`
+
+---
+
+### slots?
+
+```ts
+optional slots?: Record<string, Node[]>;
+```
+
+Defined in: `@xmachines/json-render-dom`

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

@@ -6,13 +6,13 @@
 type MountFn = (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-dom/src/create-play-ui.ts#L69)
+Defined in: [packages/play-dom/src/create-play-ui.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom/src/create-play-ui.ts#L71)
 
-The mount function returned by `createPlayUI`.
+The mount function that `createPlayUI` returns.
 
-Call with `(actor, container, mountOptions?)` to start the renderer.
-Returns a `disconnect` cleanup function that stops rendering and clears
-the container.
+Call it with `(actor, container, mountOptions?)` to start the renderer.
+It returns a `disconnect` cleanup function. That function stops the render and
+clears the container.
 
 ## Parameters