@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.50

package/api/@xmachines/play-svelte/README.md

@@ -1,152 +1,160 @@
 [API](../../README.md) / @xmachines/play-svelte
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-svelte
 
-Play-branded Svelte 5 renderer for XMachines Play.
+Svelte 5 renderer for the XMachines Play architecture — connects a `PlayActor` to a `@json-render/svelte` catalog-driven UI using Svelte 5 runes and TC39 Signals.
 
-## Overview
+Part of the [xmachines-js monorepo](../../README.md).
 
-`@xmachines/play-svelte` is the first-class Svelte entrypoint for Play apps:
+## Installation
 
-- `PlayRenderer` observes `actor.currentView` with Play signals
-- UI state is bridged through `@xstate/store` and `@json-render/xstate`
-- Svelte authors still get the underlying json-render helpers they need
+```bash
+npm install @xmachines/play-svelte
+```
 
-## Install
+**Peer dependencies** (must be installed separately):
 
 ```bash
-npm install @xmachines/play-svelte
+npm install svelte@^5.46.4 xstate@^5.30.0 @xstate/store@^3.17.0 \
+  @json-render/core@^0.18.0 @json-render/svelte@^0.18.0 @json-render/xstate@^0.18.0
 ```
 
-## Quick start
+## Usage
+
+### Basic setup
+
+Define a catalog and registry once, then pass both to `PlayUIProvider` with your actor. `PlayRenderer` renders the current actor view automatically:
 
 ```svelte
+<!-- App.svelte -->
 <script lang="ts">
-	import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-svelte";
-	import { defineCatalog, schema } from "@json-render/core";
-	import { z } from "zod";
-	import Login from "./Login.svelte";
-
-	const catalog = defineCatalog(schema, {
-		components: {
-			Login: {
-				props: z.object({ title: z.string() }),
-				description: "Login screen",
-			},
-		},
-		actions: {
-			login: { params: z.object({ username: z.string() }), description: "Login" },
-		},
-	});
-
-	const registryResult = defineRegistry(catalog, {
-		components: { Login },
-		actions: {
-			login: async (params) => {
-				if (!params) return;
-				actor.send({ type: "auth.login", username: params.username });
-			},
-		},
-	});
+  import { defineRegistry, PlayUIProvider, PlayRenderer } from "@xmachines/play-svelte";
+  import { authCatalog } from "./catalog.js";
+  import Login from "./components/Login.svelte";
+  import Dashboard from "./components/Dashboard.svelte";
+
+  let { actor } = $props();
+
+  const registryResult = defineRegistry(authCatalog, {
+    components: { Login, Dashboard },
+    actions: {
+      login: async (params) => {
+        actor.send({ type: "auth.login", username: params?.username });
+      },
+      logout: async () => actor.send({ type: "auth.logout" }),
+    },
+  });
 </script>
 
 <PlayUIProvider {actor} {registryResult}>
-	<PlayRenderer />
+  <PlayRenderer />
 </PlayUIProvider>
 ```
 
-## Primary Exports
+### Lower-level: ActorProvider
 
-- `PlayUIProvider` — batteries-included composite provider (wraps `ActorProvider` + `JSONUIProvider`); pass `actor` and `registryResult` here
-- `ActorProvider` — escape hatch primitive for direct control over actor bridging and store lifecycle
-- `PlayRenderer` — zero-prop leaf; renders inside a `PlayUIProvider` or `ActorProvider` tree
-- `getActorContext()` — Svelte equivalent of `useActor()`; access the actor from inside a component rendered in the provider tree
-- `getPlayViewContext()` — access the current view spec (`PlaySpec`) from inside the provider tree
+Use `ActorProvider` directly when you need fine-grained control over rendering — for example, to wrap with a custom layout or inject the `@json-render/svelte` providers individually:
 
-## Re-exports
+```svelte
+<script lang="ts">
+  import { ActorProvider } from "@xmachines/play-svelte";
 
-This package re-exports from `@json-render/svelte`:
+  let { actor, registryResult } = $props();
+</script>
 
-- `defineRegistry` — wire Svelte components into the Play catalog (with catalog-typed action params — see below)
-- `getBoundProp` — two-way reactive binding helper for form inputs
+<ActorProvider {actor} {registryResult} fallback={loadingSnippet} onError={handleError}>
+  <!-- children rendered inside StateProvider tree -->
+  {@render children()}
+</ActorProvider>
+```
 
-Types: `BaseComponentProps`, `ComponentFn`, `ComponentContext`, `RenderErrorHandler`
+### Accessing the actor from child components
 
-For anything else (`schema`, `Renderer`, `JsonUIProvider`, context helpers), import from `@json-render/svelte` directly.
+```ts
+import { getActorContext } from "@xmachines/play-svelte";
 
-## PlayUIProvider / PlayRenderer behavior
+// Inside a Svelte component that is a descendant of ActorProvider:
+const actor = getActorContext();
+actor.send({ type: "some.event" });
+```
 
-- `PlayUIProvider` owns actor bridging, signal observation, and store lifecycle. `PlayRenderer` is a zero-prop leaf that renders inside the provider tree.
-- `PlayRenderer` watches `actor.currentView` (via provider context) and rerenders when the active view changes.
-- Action handlers are defined as async functions in `defineRegistry({ actions: { login: async (params) => actor.send(...) } })` and bundled in `registryResult`. There is no `actions` prop on `PlayRenderer`.
-- If you do not pass a `store` to `PlayUIProvider`, it creates an internal `@xstate/store` atom from `view.spec.state`.
-- If you do pass a `store` to `PlayUIProvider`, that external store wins and no internal store is created for the view.
+## API Summary
 
-## Error handling
+### Components
 
-The provider tree has two layers of error boundaries:
+| Component          | Description                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `<PlayUIProvider>` | Batteries-included composite — wraps `ActorProvider` + `JsonUIProvider`. Standard entry point for actor-driven UI.    |
+| `<ActorProvider>`  | Primitive provider — owns actor lifecycle, signal subscription, per-view `StateStore`, and `onRenderError` injection. |
+| `<PlayRenderer>`   | Zero-prop leaf component — reads `getPlayViewContext()` and renders `<Renderer>` from `@json-render/svelte`.          |
 
-### Outer boundary — `onError` and `fallback`
+### Functions
 
-Wraps the entire renderer. Triggered when the spec state or store setup throws, or when the inner boundary is not present. These props are passed to `PlayUIProvider` (or `ActorProvider`).
+| Function                           | Description                                                                                                                                                                                         |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineRegistry(catalog, options)` | Creates a typed component registry. Wraps `@json-render/svelte`'s `defineRegistry` with catalog-typed `params` on action handlers. Import from `@xmachines/play-svelte`, not `@json-render/svelte`. |
+| `getActorContext()`                | Returns the `PlayActor` from the nearest `ActorProvider` ancestor. Throws if called outside the provider tree.                                                                                      |
+| `getPlayViewContext()`             | Returns the `ViewContextValue` (spec, registry, handlers, store) from the nearest `ActorProvider` ancestor.                                                                                         |
+| `setActorContext(actor)`           | Sets the actor context — used internally by `ActorProvider`.                                                                                                                                        |
 
-- **`fallback`** — a Svelte snippet rendered when `currentView` is `null` or when the outer boundary catches an error.
-- **`onError`** — called when the outer boundary catches an error. Receives the error and a `reset` callback.
+### Types
 
-```svelte
-<PlayUIProvider
-  {actor}
-  {registryResult}
-  fallback={errorSnippet}
-  onError={(error, reset) => {
-    console.error("Outer render error:", error);
-    // reset(); // attempt recovery
-  }}
->
-  <PlayRenderer />
-</PlayUIProvider>
-```
+| Type                       | Description                                                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `ActorProviderProps`       | Props for `<ActorProvider>`: `actor`, `registryResult`, optional `store`, `fallback` snippet, `onError`, `onRenderError`. |
+| `PlayUIProviderProps`      | Extends `ActorProviderProps` with optional `validationFunctions`, `navigate`, and `functions`.                            |
+| `ViewContextValue`         | The view context shape provided by `ActorProvider` and consumed by `PlayRenderer`.                                        |
+| `PlayActor`                | `AbstractActor<AnyActorLogic> & Viewable` — the expected actor shape.                                                     |
+| `DefineRegistryOptions<C>` | Options for `defineRegistry`: `components`, catalog-typed `actions`, and `onRenderError`.                                 |
+| `ActionFn<C, K>`           | Per-action handler type with params inferred from catalog.                                                                |
+| `Actions<C>`               | Map of catalog-typed action handlers.                                                                                     |
+| `RenderErrorHandler`       | Callback `(error: unknown, elementType: string) => void` invoked when a catalog component throws.                         |
 
-### Inner boundary — `onRenderError`
+### Re-exports from `@json-render/svelte`
 
-Each catalog element rendered by `@json-render/svelte` is individually wrapped in a `<svelte:boundary>`. When an element component throws, the failed component is silently removed from the DOM while the rest of the spec continues rendering. The outer `onError` / `fallback` are **not** triggered.
+Import everything from `@xmachines/play-svelte` — these providers are re-exported for convenience:
+
+```ts
+import {
+	JsonUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	Renderer,
+	getBoundProp,
+	getStateValue,
+} from "@xmachines/play-svelte";
+```
 
-Pass `onRenderError` to `PlayUIProvider` (or `ActorProvider`) — overrides any registry-level handler — or bake it into `defineRegistry`. `PlayRenderer` no longer accepts this prop.
+## Testing
 
-```svelte
-<!-- via PlayUIProvider prop -->
-<PlayUIProvider
-  {actor}
-  {registryResult}
-  onRenderError={(error, elementType) => {
-    console.warn(`<${elementType}> crashed:`, error);
-    reportToSentry(error, { component: elementType });
-  }}
->
-  <PlayRenderer />
-</PlayUIProvider>
+Run the test suite for this package:
+
+```bash
+npm test -w @xmachines/play-svelte
 ```
 
-```ts
-// via defineRegistry — bakes the handler into the registry
-const registryResult = defineRegistry(catalog, {
-  components: { Login, Dashboard },
-  actions: { ... },
-  onRenderError(error, elementType) {
-    myErrorReporter.capture(error, { elementType });
-  },
-});
+Or from within the package directory:
+
+```bash
+npm test
 ```
 
-When both are provided, the `PlayUIProvider` prop wins — it creates a fresh registry copy with its own handler for that render.
+Tests run with [Vitest](https://vitest.dev/) in a `jsdom` environment using `@testing-library/svelte`. Browser-specific tests are in `test/browser/` and use a separate Playwright-backed config:
+
+```bash
+# From the package directory
+npx vitest --config vitest.browser.config.ts
+```
 
-`onRenderError` is typed as `RenderErrorHandler` and exported from.
+**Coverage thresholds:** 80% lines, functions, branches, and statements (enforced via v8 provider).
 
-## Learn More
+## License
 
-- [Demo](../../../examples/@xmachines/play-svelte-demo/README.md)
-- [SvelteKit Router adapter](../play-sveltekit-router/README.md)
-- [Svelte SPA Router adapter](../play-svelte-spa-router/README.md)
+MIT — see [LICENSE](./LICENSE).
 
 @xmachines/play-svelte - Svelte renderer for XMachines Play architecture
 

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

@@ -6,7 +6,7 @@
 function defineRegistry<C>(catalog, options): DefineRegistryResult;
 ```
 
-Defined in: [packages/play-svelte/src/define-registry.ts:153](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/define-registry.ts#L153)
+Defined in: [packages/play-svelte/src/define-registry.ts:153](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/define-registry.ts#L153)
 
 Create a component registry, restoring catalog-typed `params` on action handlers.
 

package/api/@xmachines/play-svelte/functions/getActorContext.md

@@ -6,7 +6,7 @@
 function getActorContext(): PlayActor;
 ```
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L37)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L37)
 
 Get the actor from the nearest ActorProvider ancestor.
 

package/api/@xmachines/play-svelte/functions/getPlayViewContext.md

@@ -6,7 +6,7 @@
 function getPlayViewContext(): ViewContextValue;
 ```
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L58)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L58)
 
 Get the current view context from the nearest ActorProvider ancestor.
 

package/api/@xmachines/play-svelte/functions/setActorContext.md

@@ -6,7 +6,7 @@
 function setActorContext(actor): void;
 ```
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L27)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L27)
 
 ## Parameters
 

package/api/@xmachines/play-svelte/interfaces/ActorProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: ActorProviderProps
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L67)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L67)
 
 Framework-agnostic base props shared by every `ActorProvider` implementation
 (React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
@@ -35,10 +35,10 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 | Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                                                   |
 | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L154)             |
-| <a id="property-children"></a> `children`             | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L70) |
-| <a id="property-fallback"></a> `fallback?`            | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L68) |
-| <a id="property-onerror"></a> `onError?`              | (`error`, `reset`) => `void`                                                                                                                                                                                                                                     | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L69) |
-| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                                                                        | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L167)             |
-| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L156)             |
-| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L162)             |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L154)             |
+| <a id="property-children"></a> `children`             | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L70) |
+| <a id="property-fallback"></a> `fallback?`            | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L68) |
+| <a id="property-onerror"></a> `onError?`              | (`error`, `reset`) => `void`                                                                                                                                                                                                                                     | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L69) |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                                                                        | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L167)             |
+| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L156)             |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L162)             |

package/api/@xmachines/play-svelte/interfaces/DefineRegistryOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: DefineRegistryOptions\<C\>
 
-Defined in: [packages/play-svelte/src/define-registry.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/define-registry.ts#L92)
+Defined in: [packages/play-svelte/src/define-registry.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/define-registry.ts#L92)
 
 Options for `defineRegistry`.
 
@@ -19,6 +19,6 @@ Mirrors the upstream shape but replaces the untyped
 
 | Property                                             | Type                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Defined in                                                                                                                                                           |
 | ---------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actions"></a> `actions?`             | [`Actions`](../type-aliases/Actions.md)\<`C`\> | Catalog-typed action handler map. Each handler receives `params` typed to the exact schema defined in the catalog action (or `undefined` if no params were provided), plus the upstream `setState` and `state` arguments. Guard against `undefined` before accessing params: **Example** `actions: { login: async (params) => { if (!params) return; actor.send({ type: "auth.login", username: params.username }); }, logout: async () => actor.send({ type: "auth.logout" }), }`                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-svelte/src/define-registry.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/define-registry.ts#L116) |
-| <a id="property-components"></a> `components?`       | `Components`\<`C`\>                            | Svelte component implementations — keyed by catalog component name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [packages/play-svelte/src/define-registry.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/define-registry.ts#L96)   |
-| <a id="property-onrendererror"></a> `onRenderError?` | `any`                                          | Callback invoked when a catalog component throws during render. The error is caught by `@json-render/svelte`'s inner `<svelte:boundary>` that wraps each rendered element. When provided, this callback replaces the default `console.error(...)` fallback — the component is silently removed from the DOM and your callback receives the error and the element type name for custom error reporting or recovery logic. **Example** `const { registry, handlers } = defineRegistry(authCatalog, { components: { Login, Dashboard }, actions: { ... }, onRenderError(error, elementType) { console.warn(`Component <${elementType}> crashed:`, error); reportToSentry(error, { componentType: elementType }); }, });` **Param** The thrown value (not necessarily an `Error` instance). **Param** The catalog component name that crashed (e.g. `"Dashboard"`). | [packages/play-svelte/src/define-registry.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/define-registry.ts#L141) |
+| <a id="property-actions"></a> `actions?`             | [`Actions`](../type-aliases/Actions.md)\<`C`\> | Catalog-typed action handler map. Each handler receives `params` typed to the exact schema defined in the catalog action (or `undefined` if no params were provided), plus the upstream `setState` and `state` arguments. Guard against `undefined` before accessing params: **Example** `actions: { login: async (params) => { if (!params) return; actor.send({ type: "auth.login", username: params.username }); }, logout: async () => actor.send({ type: "auth.logout" }), }`                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-svelte/src/define-registry.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/define-registry.ts#L116) |
+| <a id="property-components"></a> `components?`       | `Components`\<`C`\>                            | Svelte component implementations — keyed by catalog component name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [packages/play-svelte/src/define-registry.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/define-registry.ts#L96)   |
+| <a id="property-onrendererror"></a> `onRenderError?` | `any`                                          | Callback invoked when a catalog component throws during render. The error is caught by `@json-render/svelte`'s inner `<svelte:boundary>` that wraps each rendered element. When provided, this callback replaces the default `console.error(...)` fallback — the component is silently removed from the DOM and your callback receives the error and the element type name for custom error reporting or recovery logic. **Example** `const { registry, handlers } = defineRegistry(authCatalog, { components: { Login, Dashboard }, actions: { ... }, onRenderError(error, elementType) { console.warn(`Component <${elementType}> crashed:`, error); reportToSentry(error, { componentType: elementType }); }, });` **Param** The thrown value (not necessarily an `Error` instance). **Param** The catalog component name that crashed (e.g. `"Dashboard"`). | [packages/play-svelte/src/define-registry.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/define-registry.ts#L141) |

package/api/@xmachines/play-svelte/interfaces/PlayUIProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayUIProviderProps
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L77)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L77)
 
 Framework-agnostic base props shared by every `ActorProvider` implementation
 (React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
@@ -31,13 +31,13 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 | Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                  | Defined in                                                                                                                                                                   |
 | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L154)             |
-| <a id="property-children"></a> `children`                        | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)             | [packages/play-svelte/src/actor-context.svelte.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L70) |
-| <a id="property-fallback"></a> `fallback?`                       | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)             | [packages/play-svelte/src/actor-context.svelte.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L68) |
-| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `unknown`\>                                                                                                                                                                                                                                  | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L83) |
-| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L82) |
-| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                                                                                                                                                                                     | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)               | [packages/play-svelte/src/actor-context.svelte.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L69) |
-| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                                                                        | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L167)             |
-| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L156)             |
-| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L162)             |
-| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L78) |
+| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L154)             |
+| <a id="property-children"></a> `children`                        | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)             | [packages/play-svelte/src/actor-context.svelte.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L70) |
+| <a id="property-fallback"></a> `fallback?`                       | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)             | [packages/play-svelte/src/actor-context.svelte.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L68) |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `unknown`\>                                                                                                                                                                                                                                  | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L83) |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L82) |
+| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                                                                                                                                                                                     | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)               | [packages/play-svelte/src/actor-context.svelte.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L69) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../../play-dom/type-aliases/RenderErrorHandler.md)                                                                                                                                                                                        | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L167)             |
+| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L156)             |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L162)             |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L78) |

package/api/@xmachines/play-svelte/interfaces/ViewContextValue.md

@@ -2,7 +2,7 @@
 
 # Interface: ViewContextValue
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L46)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L46)
 
 Framework-agnostic base for every framework's `ViewContextValue`.
 
@@ -18,7 +18,7 @@ type) so it is typed via `TRegistry` — the same generic used in `BaseActorProv
 
 | Property                                  | Type                                                  | Description                                                                                               | Inherited from                                                                                                                                                    | Defined in                                                                                                                                                       |
 | ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L122) |
-| <a id="property-registry"></a> `registry` | `ComponentRegistry`                                   | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L124) |
-| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L120) |
-| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-actor/src/abstract-actor.ts#L126) |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L122) |
+| <a id="property-registry"></a> `registry` | `ComponentRegistry`                                   | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L124) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L120) |
+| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-actor/src/abstract-actor.ts#L126) |

package/api/@xmachines/play-svelte/type-aliases/PlayActor.md

@@ -6,4 +6,4 @@
 type PlayActor = AbstractActor<AnyActorLogic> & Viewable;
 ```
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte/src/actor-context.svelte.ts#L21)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-svelte/src/actor-context.svelte.ts#L21)