@xmachines/docs 2.1.1 → 3.0.0

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.1.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/v3.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.1.1/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.1/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.1/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/v3.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/v3.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/v3.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/v3.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/v3.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/v3.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/type-aliases/DisposeKey.md) for the second half of that.
+
+## See
+
+[Play RFC](../../../../rfc/play.md)

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

@@ -0,0 +1,36 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / DisposablePlayUI
+
+# Type Alias: DisposablePlayUI
+
+```ts
+type DisposablePlayUI = (...args) => Cleanup;
+```
+
+Defined in: [packages/play-dom/src/create-play-ui.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom/src/create-play-ui.ts#L102)
+
+The mount function that [createPlayUI](../functions/createPlayUI.md) builds.
+
+It IS a [MountFn](MountFn.md), and it says one thing more: the mount hands back a
+[Cleanup](Cleanup.md), so a caller may release it with `using` and write no teardown.
+
+```ts
+const mount = createPlayUI(registryResult);
+{
+	using stop = mount(actor, container);
+	// stop() runs at the end of the scope, and after an exception too
+}
+```
+
+A narrowed return and not a narrowed `MountFn`: the return type of a function may
+narrow, so this costs a consumer that writes a `MountFn` nothing. The parameters come
+from `MountFn` through `Parameters`, so the two signatures cannot drift.
+
+## Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| ...`args` | `Parameters`\<[`MountFn`](MountFn.md)\> |
+
+## Returns
+
+[`Cleanup`](Cleanup.md)

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

@@ -6,7 +6,7 @@
 type MountFn = (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-dom/src/create-play-ui.ts#L71)
+Defined in: [packages/play-dom/src/create-play-ui.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom/src/create-play-ui.ts#L78)
 
 The mount function that `createPlayUI` returns.
 
@@ -14,6 +14,11 @@ 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 a plain function here, because a consumer WRITES a value of this type
+to wrap or to stand in for a mount. A [Cleanup](Cleanup.md) return would refuse every such
+function that hands a plain release back. [DisposablePlayUI](DisposablePlayUI.md) narrows it for the
+value that [createPlayUI](../functions/createPlayUI.md) builds, which nothing writes by hand.
+
 ## Parameters
 
 | Parameter   | Type                                                                                                                                                                                          |

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

@@ -4,7 +4,7 @@
 
 **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.1.1-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-3.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.
 
@@ -33,19 +33,22 @@ 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 `DisposableBrowserHistory`                                                    |
+| `createRouter(options)`                       | Creates a `DisposableVanillaRouter` from a `BrowserHistory` and a `RouteTree`, which `using` releases              |
+| `connectRouter(options)`                      | Connects a `VanillaRouter` 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                                    |
+| `DisposableBrowserHistory`                    | What `createBrowserHistory` returns: `subscribe` hands a `Cleanup` back, and the history itself is a `Disposable`  |
 | `BrowserWindow`                               | Structural window interface (accepts `Window`, JSDOM, or any test double)                                          |
-| `VanillaRouter`                               | Interface for the router wrapper                                                                                   |
+| `VanillaRouter<History>`                      | The router wrapper. `History` carries the history of the caller, so a `DisposableBrowserHistory` stays one         |
+| `DisposableVanillaRouter<History>`            | What `createRouter` returns: a `VanillaRouter` that carries the dispose key, so a `using` scope holds it           |
 | `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`                                                                    |
+| `DISPOSE`, `Cleanup`                          | The release protocol that `subscribe` and `DisposableBrowserHistory` name, re-exported from `@xmachines/play`      |
 
 ## Quick Start
 
@@ -121,17 +124,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:**
 
@@ -139,7 +142,7 @@ The interface accepts `window`, a JSDOM window, or every other object that imple
 
 ### `createRouter(options)`
 
-This function creates a `VanillaRouter` around a `history` and a `routeTree`. Its setup flow is the same as the setup flow of TanStack Router.
+This function creates a `DisposableVanillaRouter` around a `history` and a `routeTree`. Its setup flow is the same as the setup flow of TanStack Router.
 
 ```typescript
 // routeTree and history from the Quick Start above
@@ -149,6 +152,19 @@ 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 return is a `DisposableVanillaRouter`. 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:
@@ -268,9 +284,12 @@ MIT — see [LICENSE](LICENSE).
 
 ## Interfaces
 
+- [BasePathOptions](interfaces/BasePathOptions.md)
 - [BrowserHistory](interfaces/BrowserHistory.md)
 - [BrowserWindow](interfaces/BrowserWindow.md)
 - [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [DisposableBrowserHistory](interfaces/DisposableBrowserHistory.md)
+- [DisposableVanillaRouter](interfaces/DisposableVanillaRouter.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RoutableActor](interfaces/RoutableActor.md)
 - [RouteLookupContract](interfaces/RouteLookupContract.md)
@@ -278,8 +297,17 @@ MIT — see [LICENSE](LICENSE).
 - [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
 
 - [connectRouter](functions/connectRouter.md)

package/api/@xmachines/play-dom-router/classes/DomRouterBridge.md

@@ -2,7 +2,7 @@
 
 # Class: DomRouterBridge
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-dom-router/src/dom-router-bridge.ts#L26)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L27)
 
 The DOM router bridge — it puts a BrowserHistory from `createBrowserHistory`
 behind the `RouterBridgeBase` protocol.
@@ -19,7 +19,7 @@ It overrides two optional hooks:
 - `getInitialRouterSearch` → `history.location.search`
 
 The bridge inherits the prevention of a circular update, the
-restore-or-deeplink detection, and the `lastSyncedPath` deduplication from
+restore-or-deeplink detection, and the echo suppression of both directions from
 `RouterBridgeBase`.
 
 Use `connectRouter` for the usual case. Use this class directly when you need
@@ -37,10 +37,11 @@ full control of the connection lifecycle.
 new DomRouterBridge(
    actor,
    routeMap,
-   history): DomRouterBridge;
+   history,
+   options?): DomRouterBridge;
 ```
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-dom-router/src/dom-router-bridge.ts#L34)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L35)
 
 #### Parameters
 
@@ -49,6 +50,7 @@ Defined in: [play-dom-router/src/dom-router-bridge.ts:34](https://gitlab.com/xma
 | `actor`    | [`RoutableActor`](../interfaces/RoutableActor.md)             | A `Routable` actor with `currentRoute` and `send`.                                                                                   |
 | `routeMap` | [`RouteLookupContract`](../interfaces/RouteLookupContract.md) | The route lookup for both directions. Every object that satisfies [RouteLookupContract](../interfaces/RouteLookupContract.md) works. |
 | `history`  | [`BrowserHistory`](../interfaces/BrowserHistory.md)           | The BrowserHistory instance from `createBrowserHistory`.                                                                             |
+| `options?` | [`BasePathOptions`](../interfaces/BasePathOptions.md)         | -                                                                                                                                    |
 
 #### Returns
 
@@ -58,6 +60,84 @@ Defined in: [play-dom-router/src/dom-router-bridge.ts:34](https://gitlab.com/xma
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
 
+## Accessors
+
+### basePath
+
+#### Get Signature
+
+```ts
+get basePath(): string;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:255](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L255)
+
+The resolved URL prefix that the machine of this bridge is mounted under, or `""`
+when the machine owns the complete router.
+
+##### Returns
+
+`string`
+
+The resolved URL prefix of the mount, or `""` when the machine owns the complete router.
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePath`](../../play-router/classes/RouterBridgeBase.md#basepath)
+
+---
+
+### basePathParams
+
+#### Get Signature
+
+```ts
+get basePathParams(): Readonly<Record<string, string>>;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L284)
+
+The resolved values of the `:param` segments of the mount, or `{}` for a prefix
+without a param.
+
+These params belong to the HOST: the host wrote the prefix and resolved the
+values, and they describe the route of the host and not the route of the machine.
+They therefore travel in NO `play.route` event. The machine is authoritative over
+its own params, and `event.params` holds what the pattern of the machine
+declares, and nothing else.
+
+They live here instead, because a value that reached the actor on a navigation
+ALONE would go stale: `setBasePath()` can move the mount while the machine stays
+on the same route, no event goes out, and `event.params` would then contradict
+`basePath`. A read of this accessor cannot go stale.
+
+A machine that needs the identity of its host — a `machineId`, a tenant — takes
+it through the `input` of the actor, where it belongs: that identity decides
+WHICH machine runs, and it is not a param of a route inside the machine.
+
+##### Example
+
+```typescript
+bridge.basePath; // "/abc123/play"
+bridge.basePathParams; // { machineId: "abc123" }
+```
+
+##### Returns
+
+`Readonly`\<`Record`\<`string`, `string`\>\>
+
+The resolved values of the `:param` segments of the mount, or `{}` for a prefix
+without a param.
+
+These params belong to the HOST, so they travel in NO `play.route` event — the
+machine is authoritative over its own params. This accessor is therefore the one
+way a host reads them back, and it cannot go stale: `setBasePath()` can move the
+mount while the machine stays on the same route, and no event goes out.
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/classes/RouterBridgeBase.md#basepathparams)
+
 ## Methods
 
 ### connect()
@@ -66,7 +146,7 @@ Defined in: [play-dom-router/src/dom-router-bridge.ts:34](https://gitlab.com/xma
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L158)
+Defined in: [play-router/src/router-bridge-base.ts:506](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L506)
 
 Connects the router bridge to the Actor.
 
@@ -76,7 +156,7 @@ in its own way.
 
 The order of these steps is part of the contract of the bridge:
 
-- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The constructor seeds `lastActorRoute` from `actor.currentRoute`, and it records no location
 - The method installs the actor watcher before the router subscriptions of the adapter
 - The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
 
@@ -100,7 +180,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L270)
+Defined in: [play-router/src/router-bridge-base.ts:728](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L728)
 
 Disconnects the router bridge from the Actor.
 
@@ -114,3 +194,65 @@ framework.
 #### Inherited from
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
+
+---
+
+### setBasePath()
+
+```ts
+setBasePath(basePath?, basePathParams?): void;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L324)
+
+Moves the machine to a different mount point, while it stays connected.
+
+This is the "load and unload" half of a shared router. It moves WHERE an actor is
+mounted, and never WHICH actor is mounted: the actor, the route map, and its LRU
+cache all stay, and nothing goes away.
+
+An actor never changes identity. A prefix that IDENTIFIES the actor — a
+`machineId` that names the document it runs — therefore never moves through this
+method: a new identity is a new actor, and a new actor takes a new bridge, because
+`connect()` permits one bridge for each actor. The segments that move here are the
+ones that LOCATE: a region, a locale, a tenant, a workspace slug.
+
+The call then brings the location in step with the NEW prefix. A location inside
+the new mount runs the same first-synchronization decision as `connect()`: it
+drives the actor, and a restore keeps the route of the actor. A location OUTSIDE
+the new mount is the old mount in practice, so the bridge writes the new one
+itself, and it keeps the route of the actor while it does so — nothing else moves
+the address bar. A call that resolves to the current prefix changes no location,
+and it therefore reconciles nothing.
+
+#### Parameters
+
+| Parameter         | Type                                       | Description                                                                                                                                                      |
+| ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `basePath?`       | `string`                                   | The new prefix, as a pattern or as a concrete path. An absent value, `""`, and `"/"` all remove the prefix, and they give the machine the complete router again. |
+| `basePathParams?` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of `basePath`.                                                                                                               |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+For a prefix that resolves to one concrete path never.
+
+#### Throws
+
+When a `:param` of the prefix has no value.
+
+#### Example
+
+```typescript
+// The host moved this actor to another place in its URL space. `machineId` names
+// WHICH document the actor runs, and it does not change: a new identity is a new
+// actor, and therefore a new bridge, because one actor takes one bridge.
+bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
+```
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/classes/RouterBridgeBase.md#setbasepath)