@xmachines/docs 2.2.0 → 4.0.0

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

@@ -2,17 +2,18 @@
 
 # Interface: MountOptions
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/create-play-ui.ts#L49)
+Defined in: [packages/play-dom/src/create-play-ui.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L50)
 
 The mount options of the `MountFn` that `createPlayUI` returns.
 
 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.
+`validationFunctions`, `navigate`, `onRenderError`, `onError`, and `fallback`) one
+time.
 
 ## Properties
 
 | 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.2.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.2.0/packages/play-dom/src/create-play-ui.ts#L55) |
+| <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:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L62) |
+| <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:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L56) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayDomOptions
 
-Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/types.ts#L23)
+Defined in: [packages/play-dom/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L23)
 
 The options of `PlayRenderer`.
 
@@ -17,14 +17,16 @@ reads them at `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`                                                                                                 | 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.2.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.2.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.2.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) | -                                                                                                                                |
+| 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` \| (() => `HTMLElement`) \| `null`                                                          | The optional element that the renderer shows when `currentView` is `null`, and after a failure of a rebuild that it contains. The renderer shows it for EVERY null view, and not for the first mount only: a view that returns to `null` after a view that was not `null` also shows it. The four framework providers hold the same rule for their placeholder content. The renderer shows it after a failure of a rebuild too. This option turns nothing on: the renderer contains such a failure always, and this option says only what the empty container shows. The next view that renders clears the container, which removes the element. **One element belongs to one renderer.** `appendChild` MOVES a node. Two renderers that hold the same element therefore take it from each other on every null view, and the container of the first one goes empty without a notice. Build one element for each `PlayRenderer`. A FUNCTION also works here. The renderer calls it at the first moment that it needs the element, and it keeps the result, so a renderer whose view is never null builds nothing. [CreatePlayUIOptions.fallback](CreatePlayUIOptions.md#property-fallback) passes such a function for each mount. A producer that THROWS is contained on BOTH paths — a null view, and a rebuild that failed — and the renderer writes it to `console.error` and NOT to [PlayDomOptions.onError](#property-onerror). On the second path the renderer calls the producer from inside the containment of the view, and a second trip through `onError` would report the failure of the fallback as a failure of the view. The container stays empty.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                      | [packages/play-dom/src/types.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L132) |
+| <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/v4.0.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-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                              | The optional handler of a failure of a complete rebuild of the view. This option is NOT the same as `onRenderError`, which [UIProviderOptions](UIProviderOptions.md) gives: the inner renderer routes a render error of one component, and a rejection of one action handler, to `onRenderError`. It contains each of them per element, and the rebuild continues. `onError` receives the failure of the complete rebuild that no per-element boundary caught. The renderer CONTAINS a rebuild that throws, with this option and without it: it resets the state of the failed rebuild, so that the next emission makes a complete render again, and it clears the container. `connect()` renders the first view synchronously, so a bad initial view makes `connect()` throw no more. A WRITE of the store takes the same path. The renderer resolves the props of every element that the write touched, so a `$computed` function that throws on the new state aborts that render too. The renderer contains such a failure as well, and the action handler that wrote the state receives no exception. This option says WHERE the report goes. Without it, the renderer writes the contained failure to `console.error`. A handler that THROWS reaches no caller: the renderer contains that throw too, and it writes the throw to `console.error`. A host that must escalate a failure raises it from a task of its own — `queueMicrotask(() => { throw error; })` — which reaches the global handler of the page and leaves the containment whole. The five renderers hold this one rule. The second parameter is the RESET, for a retry that the host starts — a "Retry" button of its own. It renders the view that the actor holds at the MOMENT OF THE CALL, so a host that keeps the callback cannot rewind the screen to the view that failed. A reset that the host calls from inside this handler does nothing, because no input changed between the two attempts, and a reset after `disconnect()` does nothing. A reset belongs to ONE connection. `connect()` starts a connection, and the reset of a report of an older connection does nothing. A host that calls `connect()` again from inside this handler abandons the connection that reported. The "Retry" button of that report must not render into the connection that took its place. Call the reset of the newest report. This option matches the `onError` prop of the framework renderer providers, and the five renderers hold the same three rules for the reset. | -                                                                                                                      | [packages/play-dom/src/types.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/types.ts#L100) |
+| <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/v4.0.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/v4.0.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/type-aliases/Cleanup.md

@@ -0,0 +1,38 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / Cleanup
+
+# Type Alias: Cleanup
+
+```ts
+type Cleanup = () => void & { [Key in DisposeKey]: () => void };
+```
+
+Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L66)
+
+The release of a subscription. A caller runs it, or a scope releases it.
+
+The type is a function AND a `Disposable`, so one value serves both forms. A caller
+that holds the release in a field and runs it from a teardown keeps that code. A
+caller inside one scope writes `using` and writes no teardown at all:
+
+```ts
+// The explicit form. It stays correct.
+const stop = watchSignal(count, render);
+stop();
+
+// The scoped form. The scope releases it, and an exception releases it too.
+{
+	using stop = watchSignal(count, render);
+	render(count.get());
+}
+```
+
+`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
+`"lib": ["ESNext"]` of the consumer. The publishable packages build at
+`target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
+how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
+still calls it as a function, and a consumer that declares a lower `lib` still reads
+the type. See [DisposeKey](../../play/index/type-aliases/DisposeKey.md) for the second half of that.
+
+## See
+
+[Play RFC](../../../../rfc/play.md)

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

@@ -3,10 +3,10 @@
 # Type Alias: MountFn
 
 ```ts
-type MountFn = (actor, container, options?) => () => void;
+type MountFn = (actor, container, options?) => Cleanup;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-dom/src/create-play-ui.ts#L71)
+Defined in: [packages/play-dom/src/create-play-ui.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom/src/create-play-ui.ts#L94)
 
 The mount function that `createPlayUI` returns.
 
@@ -14,14 +14,36 @@ 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.
 
+The return is the release of the mount. A caller runs it, or a scope releases it:
+
+```ts
+const mount = createPlayUI(registryResult);
+{
+	using stop = mount(actor, container);
+	// stop() runs at the end of the scope, and after an exception too
+}
+```
+
+A `Cleanup` IS a `() => void`, so a caller that runs the release keeps that code. A
+consumer that WRITES a value of this type — a wrapper of a mount, or a stand-in for
+one — builds its release with `asCleanup` of `@xmachines/play`, which this package
+re-exports:
+
+```ts
+const mount: MountFn = (actor, container, options) => {
+	const stop = realMount(actor, container, options);
+	return asCleanup(() => stop());
+};
+```
+
 ## Parameters
 
-| Parameter   | Type                                                                                                                                                                                          |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) |
-| `container` | `HTMLElement`                                                                                                                                                                                 |
-| `options?`  | [`MountOptions`](../interfaces/MountOptions.md)                                                                                                                                               |
+| Parameter   | Type                                                           |
+| ----------- | -------------------------------------------------------------- |
+| `actor`     | [`ViewActor`](../../play-view/index/type-aliases/ViewActor.md) |
+| `container` | `HTMLElement`                                                  |
+| `options?`  | [`MountOptions`](../interfaces/MountOptions.md)                |
 
 ## Returns
 
-() => `void`
+[`Cleanup`](Cleanup.md)

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

@@ -4,22 +4,28 @@
 
 **Vanilla DOM router (Browser History API) for XMachines Play Architecture.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
 
 This framework-agnostic router integration keeps the `currentRoute` TC39 Signal of a Play actor and the `window.history` API of the browser in step. It needs no framework. It implements the same [`RouterBridgeBase`](../play-router/README.md) pattern as every other router adapter in the XMachines ecosystem.
 
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-dom-router @xmachines/play-router @xmachines/play-actor
+pnpm add @xmachines/play-dom-router @xmachines/play-router
 ```
 
-Peer dependency:
+**Peer dependency.** Install it with the package:
 
 ```bash
-pnpm add xstate@^5.31.0
+pnpm add @xmachines/play
 ```
 
+- `@xmachines/play` — the release protocol. This barrel re-exports `asCleanup`, `DISPOSE` and `Cleanup` from it.
+
+`@xmachines/play-router` is a dependency of this package already. Install it directly to
+reach `@xmachines/play-router/xstate`, which holds `createRouteMap` and
+`extractMachineRoutes`.
+
 ## Overview
 
 [`@xmachines/play-dom-router`](README.md) connects a Play actor to the browser URL through the `DomRouterBridge` (extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md)):
@@ -33,32 +39,55 @@ pnpm add xstate@^5.31.0
 
 | Export                                        | Description                                                                                                        |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `createBrowserHistory(options)`               | Wraps `window.history` with a subscribable `BrowserHistory` interface                                              |
-| `createRouter(options)`                       | Creates a `VanillaRouter` from a `BrowserHistory` and a `RouteTree`                                                |
-| `connectRouter(options)`                      | Connects a `VanillaRouter` to a `Routable` actor — returns a `disconnect` cleanup function                         |
+| `createBrowserHistory(options)`               | Wraps `window.history`. It returns a `BrowserHistory`, which `using` releases                                      |
+| `createRouter(options)`                       | Creates a `VanillaRouter` from a `BrowserHistory` and a `RouteTree`, which `using` releases                        |
+| `connectRouter(options)`                      | Connects a history to a `Routable` actor — returns a `RouterConnection`, which `using` releases                    |
 | `DomRouterBridge`                             | The low-level bridge class. It extends `RouterBridgeBase`. Use it directly for full lifecycle control              |
-| `createRouteMap`                              | It comes from `@xmachines/play-router`. It builds the bidirectional path ↔ state ID map                            |
-| `BrowserHistory`                              | Interface for the history wrapper                                                                                  |
+| `BrowserHistory`                              | Interface for the history wrapper. Implement it to inject a history of your own — see the note below               |
 | `BrowserWindow`                               | Structural window interface (accepts `Window`, JSDOM, or any test double)                                          |
-| `VanillaRouter`                               | Interface for the router wrapper                                                                                   |
+| `VanillaRouter`                               | The router wrapper: a history, a route tree, and the release of the history under two keys                         |
 | `ConnectRouterOptions`                        | Options type for `connectRouter`                                                                                   |
 | `RouteLookupContract`                         | Structural interface for bidirectional route lookup                                                                |
 | `RoutableActor`                               | Minimal actor interface from `@xmachines/play-router` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)` |
 | `RouterBridge`, `PlayRouteEvent`              | Types re-exported from `@xmachines/play-router`                                                                    |
-| `RouteMap`, `RouteMapping`, `RouteMapOptions` | Types re-exported from `@xmachines/play-router`                                                                    |
+| `RouteMap`, `RouteMapping`, `RouteMapOptions` | The route map class and its types, re-exported from `@xmachines/play-router`                                       |
+| `asCleanup`, `DISPOSE`, `Cleanup`             | The release protocol that `BrowserHistory` names, re-exported from `@xmachines/play`                               |
+
+### Implementing `BrowserHistory`
+
+`subscribe` returns a `Cleanup`, and the history carries the dispose key. A history that you inject for a test or for SSR therefore writes two things that a plain object does not:
+
+```typescript
+import { asCleanup, DISPOSE, type BrowserHistory } from "@xmachines/play-dom-router";
+
+const history: BrowserHistory = {
+	// ...
+	subscribe(listener) {
+		listeners.add(listener);
+		return asCleanup(() => void listeners.delete(listener));
+	},
+	destroy() {
+		listeners.clear();
+	},
+	[DISPOSE]() {
+		this.destroy();
+	},
+};
+```
+
+`asCleanup` gives the function back as itself, with the dispose key added, so a caller that runs the release keeps that code. A caller that writes `using` releases at the end of the scope, and after an exception too.
+
+Of this interface `connectRouter` reads three members — `location`, `push` and `subscribe` — and it releases the history never. The type asks for the whole of it, because that is the type of a history, and a test that stands in for one builds it from a factory rather than from a narrower type.
 
 ## Quick Start
 
 ```typescript
 import { createMachine } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 // 1. Define a routable machine — states carry meta.route
 const machine = createMachine(
@@ -82,8 +111,8 @@ const history = createBrowserHistory({ window });
 // 4. Create router
 const router = createRouter({ routeTree, history });
 
-// 5. Start actor and connect
-const actor = definePlayer({ machine })();
+// 5. Start actor and connect — `connectRouter` needs the routing capability
+const actor = definePlayer({ machine, actor: compose(PlayerActor, withRouting) })();
 actor.start();
 
 const disconnect = connectRouter({ actor, router, routeMap });
@@ -121,17 +150,17 @@ history.destroy();
 
 **`BrowserHistory` interface:**
 
-| Method                  | Description                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------- |
-| `location`              | Read-only `{ pathname, search, hash, state }`                                                        |
-| `push(path, state?)`    | Push a new entry to history                                                                          |
-| `replace(path, state?)` | Replace the current history entry                                                                    |
-| `go(delta)`             | Navigate relative to current position                                                                |
-| `back()`                | Navigate backward                                                                                    |
-| `forward()`             | Navigate forward                                                                                     |
-| `subscribe(listener)`   | Subscribe to location changes — returns unsubscribe function                                         |
-| `createHref(path)`      | Create an href from a path                                                                           |
-| `destroy()`             | Cleans up. It removes the listeners, and it restores the patched methods when it is the last wrapper |
+| Method                  | Description                                                                                              |
+| ----------------------- | -------------------------------------------------------------------------------------------------------- |
+| `location`              | Read-only `{ pathname, search, hash, state }`                                                            |
+| `push(path, state?)`    | Push a new entry to history                                                                              |
+| `replace(path, state?)` | Replace the current history entry                                                                        |
+| `go(delta)`             | Navigate relative to current position                                                                    |
+| `back()`                | Navigate backward                                                                                        |
+| `forward()`             | Navigate forward                                                                                         |
+| `subscribe(listener)`   | Subscribe to location changes — returns an unsubscribe function, a `Cleanup` from `createBrowserHistory` |
+| `createHref(path)`      | Create an href from a path                                                                               |
+| `destroy()`             | Cleans up. It removes the listeners, and it restores the patched methods when it is the last wrapper     |
 
 **`BrowserWindow` interface:**
 
@@ -149,9 +178,22 @@ const router = createRouter({ routeTree, history });
 // router.destroy() — calls history.destroy()
 ```
 
+Or let a scope release it, which also releases the history on an exception:
+
+```typescript
+using router = createRouter({ routeTree, history });
+```
+
+The dispose key and `destroy()` run the same body, and the release is idempotent, so a
+caller that keeps `destroy()` keeps it.
+
+**The release covers the history alone.** `connectRouter` hands back its own
+`RouterConnection`, and a scope that ends releases no connection for you. Release the
+connection first, then the router.
+
 ### `connectRouter(options)`
 
-This function connects a `VanillaRouter` to a `Routable` actor. It does all the work in both directions:
+This function connects a history to a `Routable` actor. It does all the work in both directions:
 
 - On connect: it sets the actor state from the initial URL, or it writes the actor route to the browser. The bridge detects a restore and a deep link.
 - While it is connected: each actor route change goes to the history, and each browser navigation sends a `play.route` event.
@@ -159,8 +201,8 @@ This function connects a `VanillaRouter` to a `Routable` actor. It does all the
 
 ```typescript
 const disconnect = connectRouter({
-	actor, // RoutableActor — any AbstractActor subclass satisfies this structurally
-	router, // VanillaRouter from createRouter()
+	actor, // RoutableActor — an actor of the `PlayActor` contract that adds `Routable` satisfies this structurally
+	router, // the router from createRouter(), or any { history }
 	routeMap, // RouteLookupContract — any object with getStateIdByPath / getPathByStateId
 });
 
@@ -170,11 +212,11 @@ disconnect();
 
 **`ConnectRouterOptions`:**
 
-| Option     | Type                  | Description                                    |
-| ---------- | --------------------- | ---------------------------------------------- |
-| `actor`    | `RoutableActor`       | The actor to keep in step with the browser URL |
-| `router`   | `VanillaRouter`       | Router from `createRouter()`                   |
-| `routeMap` | `RouteLookupContract` | Bidirectional path ↔ state ID lookup           |
+| Option     | Type                  | Description                                                                                                        |
+| ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `actor`    | `RoutableActor`       | The actor to keep in step with the browser URL                                                                     |
+| `router`   | `{ history }`         | The router from `createRouter()`, or any `{ history }`. Of the history it reads `location`, `push` and `subscribe` |
+| `routeMap` | `RouteLookupContract` | Bidirectional path ↔ state ID lookup                                                                               |
 
 **`RouteLookupContract`:**
 
@@ -187,44 +229,18 @@ interface RouteLookupContract {
 
 The bridge accepts every object that implements this structural interface. A `RouteMap` instance from `@xmachines/play-router`, a subclass, and a test double all work.
 
-### `createRouteMap` (re-export)
+### `createRouteMap` — from `@xmachines/play-router/xstate`
 
-This function comes from `@xmachines/play-router`. It builds a bidirectional `RouteMap` from an XState machine:
+This package re-exports it never: the barrel names no state machine. The function builds a bidirectional `RouteMap` from an XState machine:
 
 ```typescript
-import { createRouteMap } from "@xmachines/play-dom-router";
-
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // machine from the Quick Start above (states carry meta.route)
 const routeMap = createRouteMap(machine);
 routeMap.getStateIdByPath("/dashboard"); // "dashboard"
 routeMap.getPathByStateId("dashboard"); // "/dashboard"
 ```
 
-## URLPattern Support
-
-This package matches each route pattern with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern), through [`@xmachines/play-router`](../play-router/README.md). URLPattern is native in Node.js 24+ and in a modern browser (Chrome 95+, Firefox 117+, Safari 16.4+). In an older environment, load a polyfill **before** you import this package. See [`@xmachines/play-router`](../play-router/README.md) for the details.
-
-## Testing
-
-Run tests in isolation:
-
-```bash
-pnpm test
-# or from monorepo root:
-pnpm --filter @xmachines/play-dom-router test
-```
-
-The tests run in a Node.js environment with the `URLPattern` polyfill setup. The browser tests are in `test/browser/`. They run separately, through `vitest.browser.config.ts`.
-
-Coverage thresholds:
-
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 75%       |
-| Statements | 80%       |
-
 ## Architecture
 
 The bridge-first data flow:
@@ -253,10 +269,12 @@ Browser URL
 
 ## Related Packages
 
-- [@xmachines/play-router](../play-router/README.md) — `RouterBridgeBase`, `createRouteMap`, `extractMachineRoutes`
-- [@xmachines/play-actor](../play-actor/README.md) — `AbstractActor`, `Routable`, `Viewable`; all subclasses satisfy `RoutableActor` structurally
+- [@xmachines/play-router](../play-router/README.md) — `RouterBridgeBase`, `RouteMap`, `Routable`
+- [@xmachines/play-router/xstate](../play-router/README.md) — `createRouteMap`, `extractMachineRoutes`
+- [@xmachines/play-actor](../play-actor/README.md) — `PlayActor`; an actor that adds `Routable` satisfies `RoutableActor` structurally
 - [@xmachines/play-dom](../play-dom/README.md) — the vanilla DOM renderer, for the view beside the routing
 - [@xmachines/play-xstate](../play-xstate/README.md) — `definePlayer`, `PlayerActor`
+- [Routing guide](../../../guides/routing.md) — the URLPattern language that a `meta.route` path declares
 
 ## License
 
@@ -265,6 +283,7 @@ MIT — see [LICENSE](LICENSE).
 ## Classes
 
 - [DomRouterBridge](classes/DomRouterBridge.md)
+- [RouteMap](classes/RouteMap.md)
 
 ## Interfaces
 
@@ -275,16 +294,23 @@ MIT — see [LICENSE](LICENSE).
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RoutableActor](interfaces/RoutableActor.md)
 - [RouteLookupContract](interfaces/RouteLookupContract.md)
-- [RouteMap](interfaces/RouteMap.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 - [RouterConnection](interfaces/RouterConnection.md)
 - [VanillaRouter](interfaces/VanillaRouter.md)
 
+## Type Aliases
+
+- [Cleanup](type-aliases/Cleanup.md)
+
+## Variables
+
+- [DISPOSE](variables/DISPOSE.md)
+
 ## Functions
 
+- [asCleanup](functions/asCleanup.md)
 - [connectRouter](functions/connectRouter.md)
 - [createBrowserHistory](functions/createBrowserHistory.md)
-- [createRouteMap](functions/createRouteMap.md)
 - [createRouter](functions/createRouter.md)