@xmachines/play-dom 1.0.0-beta.50 → 1.0.0-beta.52

package/README.md

@@ -4,7 +4,7 @@
 
 Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
 
-Part of the [xmachines-js monorepo](../../README.md).
+Part of the [XMachines Play monorepo](../../README.md).
 
 ## Installation
 
@@ -87,7 +87,9 @@ disconnect();
 
 ### `createPlayUI` — batteries-included factory with full options
 
-Use `createPlayUI` when you need render error handling, a fallback element, or a shared `registryResult` that you also need to reference programmatically (e.g. for `executeAction`).
+Use `createPlayUI` when you need render error handling, a fallback element, navigation integration, computed functions, or custom validation — or when you need to reference `registryResult` programmatically (e.g. for `executeAction`).
+
+Factory-level options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, `fallback`) are closed over at creation time and applied on every `mount()` call. Per-mount options (`store`, `loading`) are passed to `mount()` itself.
 
 ```typescript
 import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
@@ -110,6 +112,10 @@ const registryResult = defineRegistry(catalog, {
 const mount = createPlayUI(registryResult, {
 	onRenderError: console.error,
 	fallback: document.getElementById("loading")!,
+	navigate: (path) => myRouter.push(path),
+	functions: {
+		fullName: (args) => `${args.first} ${args.last}`,
+	},
 });
 
 const disconnect = mount(actor, document.getElementById("app")!);
@@ -148,35 +154,112 @@ const renderer = new PlayRenderer(container, actor, registryResult.registry, {
 renderer.connect();
 ```
 
-### `connectRenderer` — functional API (backward-compatible)
+## Provider Options
 
-`connectRenderer` is the original functional API, equivalent to creating a `PlayRenderer` and calling `connect()` in one step. Prefer `createRenderer` or `createPlayUI` for new code.
+All entry points (`createPlayUI`, `PlayRenderer`) accept the same set of UI-provider options via `UIProviderOptions`. These are forwarded into `DomRenderContext` on every render pass, making them available to component implementations via `ctx.ctx.*`.
 
-```typescript
-import { connectRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+### `functions` — named compute functions for `$computed` prop expressions
 
-const registryResult = defineRegistry(catalog, {
-	components: {
-		Home: ({ props }) => {
-			const el = document.createElement("section");
-			el.textContent = props.title;
-			return el;
-		},
+Enables `{ "$computed": "name", "args": {...} }` dynamic prop values in specs. Each function receives the resolved `args` object and returns the computed value.
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	functions: {
+		fullName: (args) => `${args.first} ${args.last}`,
+		formatDate: (args) => new Date(args.iso as string).toLocaleDateString(),
 	},
-	actions: {
-		logout: async () => actor.send({ type: "auth.logout" }),
+});
+```
+
+Without `functions`, any `$computed` expression silently resolves to `undefined` (no throw, backward-compatible).
+
+### `validationFunctions` — custom field validation
+
+Provides named validation functions for inline field validation within components. Functions receive `(value, args?)` and return `true` (valid) or `false` (invalid).
+
+Unlike the framework renderers, the DOM renderer has no automatic `ValidationProvider` tree. Components must invoke validation explicitly using `runValidationCheck` / `runValidation` from `@json-render/core`, passing `ctx.ctx.validationFunctions` as `customFunctions`.
+
+```typescript
+import { runValidationCheck } from "@json-render/core";
+
+const mount = createPlayUI(registryResult, {
+	validationFunctions: {
+		isEven: (value) => typeof value === "number" && value % 2 === 0,
+		phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)),
 	},
 });
 
-const disconnect = connectRenderer({
-	actor,
-	registry: registryResult.registry,
-	registryResult,
-	container: document.getElementById("app")!,
+// 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
+};
+```
+
+### `navigate` — programmatic navigation from action bindings
+
+A callback invoked when an action binding resolves with `onSuccess: { navigate: "/path" }`. The resolved path string is passed as the sole argument. Integrate with any router:
+
+```typescript
+// React Router / TanStack Router / any push-based router:
+const mount = createPlayUI(registryResult, {
+	navigate: (path) => myRouter.push(path),
 });
+```
 
-// Later:
-disconnect();
+With a spec binding:
+
+```json
+{
+	"on": {
+		"click": {
+			"action": "submitForm",
+			"onSuccess": { "navigate": "/dashboard" }
+		}
+	}
+}
+```
+
+When `submitForm` completes successfully, `navigate("/dashboard")` is called automatically.
+
+The function is also readable by component implementations directly via `ctx.ctx.navigate` for cases where navigation needs to be triggered outside of an action binding.
+
+### `onRenderError` — unified error handler
+
+Receives `(error, name)` for three distinct error classes:
+
+- **Component render errors** — when a `ComponentFn` throws synchronously during `renderSpec`. `name` is the catalog component name (e.g. `"Home"`).
+- **Action handler rejections (emit path)** — when an `ActionFn` throws or returns a rejected promise during `emit()`. `name` is the catalog action name (e.g. `"submitForm"`).
+- **Action handler rejections (watch path)** — when an `ActionFn` rejects during a `watch` binding callback. `name` is the catalog action name.
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	onRenderError: (err, name) => {
+		// Route to your application's error tracking
+		Sentry.captureException(err, { extra: { name } });
+	},
+});
+```
+
+The argument order matches the upstream `RenderErrorHandler` type from `@json-render/core`: **error first, name second**. This is consistent with the framework renderers (`@json-render/solid`, `@json-render/react`).
+
+Without `onRenderError`, all three error types are logged via `console.error` and swallowed. No exception propagates, and no unhandled promise rejection is created.
+
+The handler is also available to component implementations via `ctx.ctx.onRenderError`, enabling components to route their own internal errors through the same channel:
+
+```typescript
+const MyComponent: ComponentFn<typeof catalog, "MyComponent"> = ({ ctx }) => {
+	try {
+		const el = doSomethingRisky();
+		return el;
+	} catch (err) {
+		ctx.ctx.onRenderError?.(err, "MyComponent");
+		return null;
+	}
+};
 ```
 
 ## API Summary
@@ -188,36 +271,33 @@ disconnect();
 | `createRenderer(catalog, components)`    | function | One-call factory — returns `mount(actor, container, options?) → disconnect` |
 | `createPlayUI(registryResult, options?)` | function | Batteries-included factory — returns `MountFn`                              |
 | `PlayRenderer`                           | class    | Class-based renderer with `connect()` / `disconnect()` lifecycle            |
-| `connectRenderer(options)`               | function | Functional API; backward-compatible alternative to `PlayRenderer`           |
 | `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                     |
 | `renderSpec(...)`                        | function | Pure Spec → DOM renderer (low-level)                                        |
 | `schema`                                 | const    | The `@json-render/dom` schema — pass to `defineCatalog()`                   |
 
 ### Key Types
 
-| Type                     | Description                                                                            |
-| ------------------------ | -------------------------------------------------------------------------------------- |
-| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`               |
-| `ComponentContext<C, K>` | Context passed to each component: `props`, `children`, `emit`, `on`, `bindings`, `ctx` |
-| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                   |
-| `EventHandle`            | Handle returned by `on(eventName)` — has `emit()`, `shouldPreventDefault`, `bound`     |
-| `SetState`               | State updater: `(prev => next) => void`                                                |
-| `DefineRegistryResult`   | Result from `defineRegistry` — has `registry`, `handlers`, `executeAction`             |
-| `PlayDomOptions`         | Options for `PlayRenderer` and `connectRenderer`                                       |
-| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                        |
-| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                              |
-| `DomSchema`              | Type of the `schema` export                                                            |
-
-### Error Classes
-
-| Class                   | Error Code                        | Description                              |
-| ----------------------- | --------------------------------- | ---------------------------------------- |
-| `MissingCatalogError`   | `PLAY_RENDERER_MISSING_CATALOG`   | Components map was `null` or `undefined` |
-| `MissingComponentError` | `PLAY_RENDERER_MISSING_COMPONENT` | Component name not found in catalog      |
+| Type                     | Description                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------ |
+| `ComponentFn<C, K>`      | Catalog-typed component function — returns `HTMLElement \| Text \| null`                   |
+| `ComponentContext<C, K>` | Context passed to each component: `props`, `children`, `emit`, `on`, `bindings`, `ctx`     |
+| `ActionFn<C, K>`         | Catalog-typed action function — receives `(params, setState, state)`                       |
+| `EventHandle`            | Handle returned by `on(eventName)` — has `emit()`, `shouldPreventDefault`, `bound`         |
+| `SetState`               | State updater: `(prev => next) => void`                                                    |
+| `DefineRegistryResult`   | Result from `defineRegistry` — has `registry`, `handlers`, `executeAction`                 |
+| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`                                   |
+| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback`                  |
+| `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                        |
+| `MountFn`                | The mount function returned by `createPlayUI`: `(actor, container, options?) → disconnect` |
+| `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`            |
+| `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                            |
+| `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                  |
+| `DomSchema`              | Type of the `schema` export                                                                |
+| `ComputedFunction`       | Type for named compute functions used with the `functions` option                          |
 
 ## Rendering Behaviour
 
-- **Initial render is synchronous** — the container is populated before `connect()` or `connectRenderer()` returns.
+- **Initial render is synchronous** — the container is populated before `connect()` returns.
 - **Signal-driven re-renders are microtask-deferred** — `watchSignal` schedules updates on the next microtask queue tick.
 - **Null view** clears the container. A `fallback` element can be shown on initial mount when the view is `null`; it is **not** re-appended if the view later transitions back to `null` after a non-null view.
 - **Double `connect()` is safe** — calling `connect()` on an already-connected renderer auto-disconnects first.

package/dist/PlayRenderer.d.ts

@@ -18,6 +18,13 @@ import type { PlayDomOptions } from "./types.js";
  * Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
  * functions into `container` on every view transition. Cleared on `disconnect()`.
  *
+ * Options from `PlayDomOptions` (which extends `UIProviderOptions`) are all forwarded
+ * into `DomRenderContext` on every render pass:
+ * - `functions` — named compute functions for `{ $computed: "name" }` prop expressions
+ * - `validationFunctions` — custom validation functions, available at `ctx.ctx.validationFunctions`
+ * - `navigate` — navigation callback, invoked on `onSuccess: { navigate: "..." }` action bindings
+ * - `onRenderError` — called with `(error, name)` for component render errors and action handler rejections
+ *
  * **Preferred usage — via `registryResult`:**
  * ```typescript
  * import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
@@ -25,6 +32,8 @@ import type { PlayDomOptions } from "./types.js";
  * const registryResult = defineRegistry(catalog, { components, actions });
  * const renderer = new PlayRenderer(container, actor, registryResult.registry, {
  *   registryResult, // wires setState/getState from xstate store automatically
+ *   navigate: (path) => myRouter.push(path),
+ *   functions: { fullName: (args) => `${args.first} ${args.last}` },
  * });
  * renderer.connect();
  * // Later:
@@ -65,11 +74,14 @@ export declare class PlayRenderer {
      * @param container - `HTMLElement` to render into. Cleared and repopulated on every view transition.
      * @param actor     - Actor providing the `currentView` signal (must implement `Viewable`).
      * @param registry  - Component renderer map — typically `registryResult.registry` from `defineRegistry`.
-     * @param options   - Configuration:
-     *   - `registryResult` — preferred; auto-wires `setState`/`state` from the xstate store.
-     *   - `handlers`       — pre-resolved handler map (legacy; used when `registryResult` is absent).
-     *   - `store`          — external `StateStore` (controlled mode; overrides `spec.state` seeding).
-     *   - `loading`        — streaming mode flag; suppresses missing-child warnings.
+     * @param options   - Configuration (see {@link PlayDomOptions}):
+     *   - `registryResult`      — auto-wires `setState`/`state` from the xstate store.
+     *   - `store`               — external `StateStore` (controlled mode; overrides `spec.state` seeding).
+     *   - `loading`             — streaming mode flag; suppresses missing-child warnings.
+     *   - `functions`           — named compute functions for `$computed` prop expressions.
+     *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
+     *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
+     *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections; suppresses `console.error` fallback.
      */
     constructor(container: HTMLElement, actor: AbstractActor<AnyActorLogic> & Viewable, registry: DomRegistry, options?: PlayDomOptions);
     /**

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,YAAY;IAwBvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA1BzB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,aAAa,CAAsB;IAC3C;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;OASG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,UAAU,IAAI,IAAI;IAmBlB,OAAO,CAAC,MAAM;CAkGd"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,YAAY;IA2BvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA7BzB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,aAAa,CAAsB;IAC3C;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;;;;OAYG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,UAAU,IAAI,IAAI;IAmBlB,OAAO,CAAC,MAAM;CA8Fd"}

package/dist/PlayRenderer.js

@@ -40,6 +40,13 @@ function toAtomState(state) {
  * Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
  * functions into `container` on every view transition. Cleared on `disconnect()`.
  *
+ * Options from `PlayDomOptions` (which extends `UIProviderOptions`) are all forwarded
+ * into `DomRenderContext` on every render pass:
+ * - `functions` — named compute functions for `{ $computed: "name" }` prop expressions
+ * - `validationFunctions` — custom validation functions, available at `ctx.ctx.validationFunctions`
+ * - `navigate` — navigation callback, invoked on `onSuccess: { navigate: "..." }` action bindings
+ * - `onRenderError` — called with `(error, name)` for component render errors and action handler rejections
+ *
  * **Preferred usage — via `registryResult`:**
  * ```typescript
  * import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
@@ -47,6 +54,8 @@ function toAtomState(state) {
  * const registryResult = defineRegistry(catalog, { components, actions });
  * const renderer = new PlayRenderer(container, actor, registryResult.registry, {
  *   registryResult, // wires setState/getState from xstate store automatically
+ *   navigate: (path) => myRouter.push(path),
+ *   functions: { fullName: (args) => `${args.first} ${args.last}` },
  * });
  * renderer.connect();
  * // Later:
@@ -87,11 +96,14 @@ export class PlayRenderer {
      * @param container - `HTMLElement` to render into. Cleared and repopulated on every view transition.
      * @param actor     - Actor providing the `currentView` signal (must implement `Viewable`).
      * @param registry  - Component renderer map — typically `registryResult.registry` from `defineRegistry`.
-     * @param options   - Configuration:
-     *   - `registryResult` — preferred; auto-wires `setState`/`state` from the xstate store.
-     *   - `handlers`       — pre-resolved handler map (legacy; used when `registryResult` is absent).
-     *   - `store`          — external `StateStore` (controlled mode; overrides `spec.state` seeding).
-     *   - `loading`        — streaming mode flag; suppresses missing-child warnings.
+     * @param options   - Configuration (see {@link PlayDomOptions}):
+     *   - `registryResult`      — auto-wires `setState`/`state` from the xstate store.
+     *   - `store`               — external `StateStore` (controlled mode; overrides `spec.state` seeding).
+     *   - `loading`             — streaming mode flag; suppresses missing-child warnings.
+     *   - `functions`           — named compute functions for `$computed` prop expressions.
+     *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
+     *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
+     *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections; suppresses `console.error` fallback.
      */
     constructor(container, actor, registry, options = {}) {
         this.container = container;
@@ -179,19 +191,15 @@ export class PlayRenderer {
             // patch unless the StateStore contract is updated to match.
             store.update(next);
         };
-        // Warn when both registryResult and handlers are provided — handlers is silently ignored.
-        // This prevents silent data loss during migration from the legacy pattern.
-        if (this.options.registryResult && this.options.handlers) {
-            console.warn("[play-dom] Both registryResult and handlers were provided. " +
-                "handlers is ignored when registryResult is present. " +
-                "Remove the handlers option to silence this warning.");
-        }
-        // Resolve handlers: prefer registryResult (wires setState/getState from store),
-        // fall back to pre-resolved handlers map for backward compatibility.
+        // Resolve handlers from registryResult (wires setState/getState from store).
         const handlers = this.options.registryResult
             ? this.options.registryResult.handlers(() => setState, () => store.getSnapshot())
-            : (this.options.handlers ?? {});
+            : {};
         const loading = this.options.loading;
+        const functions = this.options.functions;
+        const validationFunctions = this.options.validationFunctions;
+        const navigate = this.options.navigate;
+        const onRenderError = this.options.onRenderError;
         const rerender = () => {
             // Guard: skip if PlayRenderer has been disconnected.
             // Handles the edge case where a StateStore implementation fires its
@@ -203,9 +211,9 @@ export class PlayRenderer {
                 cleanup();
             this.watchCleanups = [];
             this.container.replaceChildren();
-            const node = renderSpec(view, store, this.registry, send, handlers, undefined, undefined, undefined, loading, (cleanup) => {
+            const node = renderSpec(view, store, this.registry, send, handlers, undefined, onRenderError, functions, loading, (cleanup) => {
                 this.watchCleanups.push(cleanup);
-            });
+            }, validationFunctions, navigate);
             if (node)
                 this.container.appendChild(node);
         };

package/dist/PlayRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"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"}

package/dist/create-play-ui.d.ts

@@ -1,18 +1,27 @@
 /**
  * createPlayUI — batteries-included DOM factory.
  *
- * Takes a DefineRegistryResult (user calls defineRegistry themselves) and returns
- * a mount function. Calling mount(actor, container) starts the renderer and returns
- * a disconnect function for cleanup.
+ * Takes a `DefineRegistryResult` (the caller is responsible for calling
+ * `defineRegistry`) and returns a `MountFn`. Calling `mount(actor, container)`
+ * starts the renderer and returns a `disconnect` cleanup function.
  *
- * Parallel to <PlayUIProvider registryResult={...}> in framework renderers.
+ * Factory-level options (`functions`, `validationFunctions`, `navigate`,
+ * `onRenderError`, `fallback`) are closed over at creation time and applied on
+ * every `mount()` call. Per-mount options (`store`, `loading`) can be passed
+ * to the `mount()` call itself via `MountOptions`.
+ *
+ * Parallel to `<PlayUIProvider registryResult={...}>` in the framework renderers.
  *
  * @example
  * ```typescript
  * import { defineRegistry, createPlayUI } from "@xmachines/play-dom";
  *
  * const registryResult = defineRegistry(catalog, { components, actions });
- * const mount = createPlayUI(registryResult, { onRenderError: console.error });
+ * const mount = createPlayUI(registryResult, {
+ *   onRenderError: console.error,
+ *   navigate: (path) => myRouter.push(path),
+ *   functions: { fullName: (args) => `${args.first} ${args.last}` },
+ * });
  * const disconnect = mount(actor, document.getElementById("app")!);
  *
  * // Later:
@@ -27,30 +36,49 @@ import type { StateStore } from "@json-render/core";
 import type { DefineRegistryResult } from "./json-render/types.js";
 import type { CreatePlayUIOptions } from "./types.js";
 /**
- * Per-mount options that can override factory-level settings.
+ * Per-mount options passed to the `MountFn` returned by `createPlayUI`.
+ *
+ * These override or supplement the factory-level options on a per-actor/container
+ * basis. Factory-level options (`functions`, `validationFunctions`, `navigate`,
+ * `onRenderError`, `fallback`) are set once when calling `createPlayUI`.
  */
 export interface MountOptions {
-    /** Optional external StateStore (controlled mode). When omitted, a fresh atom is created per view. */
+    /**
+     * Optional external `StateStore` (controlled mode).
+     * When omitted, a fresh `@xstate/store` atom is created per view transition
+     * seeded from `spec.state`.
+     */
     store?: StateStore;
-    /** When true, suppresses missing-child warnings during streaming spec ingestion. */
+    /**
+     * When `true`, suppresses missing-child warnings during streaming spec ingestion
+     * and exposes `ctx.ctx.loading` to component implementations.
+     */
     loading?: boolean;
 }
 /**
- * The mount function returned by createPlayUI.
- * Call with (actor, container, mountOptions?) to start the renderer.
- * Returns a disconnect function for cleanup.
+ * The mount function returned by `createPlayUI`.
+ *
+ * Call with `(actor, container, mountOptions?)` to start the renderer.
+ * Returns a `disconnect` cleanup function that stops rendering and clears
+ * the container.
  */
 export type MountFn = (actor: AbstractActor<AnyActorLogic> & Viewable, container: HTMLElement, options?: MountOptions) => () => void;
 /**
  * Create a batteries-included DOM renderer mount function.
  *
- * The user is responsible for calling defineRegistry to produce registryResult.
- * createPlayUI closes over the registryResult and returns a mount function that
- * can be called once per actor/container pair.
+ * The caller is responsible for producing `registryResult` via `defineRegistry`.
+ * `createPlayUI` closes over it and returns a `MountFn` that can be invoked
+ * once per actor/container pair.
  *
- * @param registryResult - Result from defineRegistry() containing registry + handlers factory.
- * @param options - Optional factory-level configuration (validationFunctions, navigate, etc.)
- * @returns mount function: (actor, container, mountOptions?) → disconnect
+ * @param registryResult - Result from `defineRegistry()` — provides the registry
+ *   and the lazy handlers factory.
+ * @param options - Factory-level configuration (see {@link CreatePlayUIOptions}):
+ *   - `functions`           — named compute functions for `$computed` prop expressions.
+ *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
+ *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
+ *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections.
+ *   - `fallback`            — element shown when the actor's initial view is `null`.
+ * @returns `MountFn`: `(actor, container, mountOptions?) → disconnect`
  */
 export declare function createPlayUI(registryResult: DefineRegistryResult, options?: CreatePlayUIOptions): MountFn;
 //# sourceMappingURL=create-play-ui.d.ts.map

package/dist/create-play-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-play-ui.d.ts","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sGAAsG;IACtG,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CACrB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,YAAY,KAClB,MAAM,IAAI,CAAC;AAEhB;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC3B,cAAc,EAAE,oBAAoB,EACpC,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CA6CT"}
+{"version":3,"file":"create-play-ui.d.ts","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CACrB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,YAAY,KAClB,MAAM,IAAI,CAAC;AAEhB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC3B,cAAc,EAAE,oBAAoB,EACpC,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAmCT"}

package/dist/create-play-ui.js

@@ -1,18 +1,27 @@
 /**
  * createPlayUI — batteries-included DOM factory.
  *
- * Takes a DefineRegistryResult (user calls defineRegistry themselves) and returns
- * a mount function. Calling mount(actor, container) starts the renderer and returns
- * a disconnect function for cleanup.
+ * Takes a `DefineRegistryResult` (the caller is responsible for calling
+ * `defineRegistry`) and returns a `MountFn`. Calling `mount(actor, container)`
+ * starts the renderer and returns a `disconnect` cleanup function.
  *
- * Parallel to <PlayUIProvider registryResult={...}> in framework renderers.
+ * Factory-level options (`functions`, `validationFunctions`, `navigate`,
+ * `onRenderError`, `fallback`) are closed over at creation time and applied on
+ * every `mount()` call. Per-mount options (`store`, `loading`) can be passed
+ * to the `mount()` call itself via `MountOptions`.
+ *
+ * Parallel to `<PlayUIProvider registryResult={...}>` in the framework renderers.
  *
  * @example
  * ```typescript
  * import { defineRegistry, createPlayUI } from "@xmachines/play-dom";
  *
  * const registryResult = defineRegistry(catalog, { components, actions });
- * const mount = createPlayUI(registryResult, { onRenderError: console.error });
+ * const mount = createPlayUI(registryResult, {
+ *   onRenderError: console.error,
+ *   navigate: (path) => myRouter.push(path),
+ *   functions: { fullName: (args) => `${args.first} ${args.last}` },
+ * });
  * const disconnect = mount(actor, document.getElementById("app")!);
  *
  * // Later:
@@ -25,45 +34,37 @@ import { PlayRenderer } from "./PlayRenderer.js";
 /**
  * Create a batteries-included DOM renderer mount function.
  *
- * The user is responsible for calling defineRegistry to produce registryResult.
- * createPlayUI closes over the registryResult and returns a mount function that
- * can be called once per actor/container pair.
+ * The caller is responsible for producing `registryResult` via `defineRegistry`.
+ * `createPlayUI` closes over it and returns a `MountFn` that can be invoked
+ * once per actor/container pair.
  *
- * @param registryResult - Result from defineRegistry() containing registry + handlers factory.
- * @param options - Optional factory-level configuration (validationFunctions, navigate, etc.)
- * @returns mount function: (actor, container, mountOptions?) → disconnect
+ * @param registryResult - Result from `defineRegistry()` — provides the registry
+ *   and the lazy handlers factory.
+ * @param options - Factory-level configuration (see {@link CreatePlayUIOptions}):
+ *   - `functions`           — named compute functions for `$computed` prop expressions.
+ *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
+ *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
+ *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections.
+ *   - `fallback`            — element shown when the actor's initial view is `null`.
+ * @returns `MountFn`: `(actor, container, mountOptions?) → disconnect`
  */
 export function createPlayUI(registryResult, options = {}) {
-    const { onRenderError, fallback } = options;
-    // Note: validationFunctions, navigate, functions are json-render provider features.
-    // The DOM layer doesn't have a provider tree — these are noted for future integration
-    // if a DOM ValidationProvider equivalent is introduced in @json-render/dom.
-    // For now they are accepted in options for API parity but not forwarded.
+    const { onRenderError, fallback, functions, validationFunctions, navigate } = options;
     return function mount(actor, container, mountOptions) {
-        // Build the registry: if onRenderError is provided, inject it via Object.defineProperty
-        // (same pattern as framework renderers, centralised per D-19).
-        // Note: spreading registryResult.registry does NOT copy non-enumerable properties —
-        // this intentionally drops any registry-level onRenderError so the options-level
-        // handler has sole authority (D-19 pattern).
-        const registry = onRenderError
-            ? (() => {
-                const r = { ...registryResult.registry };
-                Object.defineProperty(r, "onRenderError", {
-                    value: onRenderError,
-                    enumerable: false,
-                    configurable: true,
-                });
-                return r;
-            })()
-            : registryResult.registry;
+        // All UIProviderOptions (onRenderError, functions, validationFunctions, navigate) are
+        // forwarded directly through PlayDomOptions → PlayRenderer → renderSpec → DomRenderContext.
         const rendererOptions = {
             registryResult,
             ...(mountOptions?.store !== undefined && { store: mountOptions.store }),
             ...(mountOptions?.loading !== undefined && { loading: mountOptions.loading }),
+            ...(functions !== undefined && { functions }),
+            ...(validationFunctions !== undefined && { validationFunctions }),
+            ...(navigate !== undefined && { navigate }),
+            ...(onRenderError !== undefined && { onRenderError }),
         };
-        const renderer = new PlayRenderer(container, actor, registry, rendererOptions);
+        const renderer = new PlayRenderer(container, actor, registryResult.registry, rendererOptions);
         renderer.connect();
-        // Handle fallback for null view on initial mount (same pattern as connectRenderer).
+        // Handle fallback for null view on initial mount.
         // connect() calls _render() synchronously so the container is already populated
         // at this point if actor.currentView is non-null.
         if (fallback != null && container.childNodes.length === 0) {

package/dist/create-play-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-play-ui.js","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBjD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC3B,cAAoC,EACpC,UAA+B,EAAE;IAEjC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC5C,oFAAoF;IACpF,sFAAsF;IACtF,4EAA4E;IAC5E,yEAAyE;IAEzE,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY;QACnD,wFAAwF;QACxF,+DAA+D;QAC/D,oFAAoF;QACpF,iFAAiF;QACjF,6CAA6C;QAC7C,MAAM,QAAQ,GAAG,aAAa;YAC7B,CAAC,CAAC,CAAC,GAAG,EAAE;gBACN,MAAM,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC;gBACzC,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,eAAe,EAAE;oBACzC,KAAK,EAAE,aAAa;oBACpB,UAAU,EAAE,KAAK;oBACjB,YAAY,EAAE,IAAI;iBAClB,CAAC,CAAC;gBACH,OAAO,CAAC,CAAC;YACV,CAAC,CAAC,EAAE;YACL,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC;QAE3B,MAAM,eAAe,GAAG;YACvB,cAAc;YACd,GAAG,CAAC,YAAY,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;YACvE,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;SAC7E,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QAC/E,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEnB,oFAAoF;QACpF,gFAAgF;QAChF,kDAAkD;QAClD,IAAI,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAED,OAAO,SAAS,UAAU;YACzB,QAAQ,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-play-ui.js","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAsCjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAC3B,cAAoC,EACpC,UAA+B,EAAE;IAEjC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,mBAAmB,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAEtF,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY;QACnD,sFAAsF;QACtF,4FAA4F;QAC5F,MAAM,eAAe,GAAG;YACvB,cAAc;YACd,GAAG,CAAC,YAAY,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;YACvE,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;YAC7E,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,EAAE,mBAAmB,EAAE,CAAC;YACjE,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC;SACrD,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAChC,SAAS,EACT,KAAK,EACL,cAAc,CAAC,QAAQ,EACvB,eAAe,CACf,CAAC;QACF,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEnB,kDAAkD;QAClD,gFAAgF;QAChF,kDAAkD;QAClD,IAAI,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAED,OAAO,SAAS,UAAU;YACzB,QAAQ,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}

package/dist/create-renderer.d.ts

@@ -73,7 +73,8 @@ import type { PlayDomOptions } from "./types.js";
  * `registryResult` (it is always provided by `createRenderer` itself and cannot be overridden).
  *
  * If you need to call `registryResult.executeAction()` programmatically (outside the emit/on
- * flow), or share the same `registryResult` with `connectRenderer`, use `defineRegistry` and
+ * flow), or pass additional provider options (`navigate`, `onRenderError`, `functions`, etc.),
+ * use `createPlayUI` (which accepts the full `CreatePlayUIOptions`) or `defineRegistry` with
  * `PlayRenderer` directly rather than `createRenderer`.
  */
 export declare function createRenderer<C extends Catalog>(catalog: C, componentMap: ComponentRegistry<C>): (actor: AbstractActor<AnyActorLogic> & Viewable, container: HTMLElement, options?: Omit<PlayDomOptions, "registryResult">) => () => void;

package/dist/create-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-renderer.d.ts","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,CACF,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,KAC5C,MAAM,IAAI,CAWd"}
+{"version":3,"file":"create-renderer.d.ts","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,CACF,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,KAC5C,MAAM,IAAI,CAWd"}

package/dist/create-renderer.js

@@ -70,7 +70,8 @@ import { defineRegistry } from "./json-render/types.js";
  * `registryResult` (it is always provided by `createRenderer` itself and cannot be overridden).
  *
  * If you need to call `registryResult.executeAction()` programmatically (outside the emit/on
- * flow), or share the same `registryResult` with `connectRenderer`, use `defineRegistry` and
+ * flow), or pass additional provider options (`navigate`, `onRenderError`, `functions`, etc.),
+ * use `createPlayUI` (which accepts the full `CreatePlayUIOptions`) or `defineRegistry` with
  * `PlayRenderer` directly rather than `createRenderer`.
  */
 export function createRenderer(catalog, componentMap) {