@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-solid-router/interfaces/PlayRouterProviderProps.md

@@ -1,14 +1,30 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterProviderProps
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterProviderProps
 
-# Interface: PlayRouterProviderProps
+# Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L14)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L50)
+
+Props for the Solid Router `PlayRouterProvider`.
+
+`router` bundles the three Solid Router hook results that drive bidirectional
+sync. Obtain these from `useNavigate()`, `useLocation()`, and `useParams()`
+in the parent component (they must be called inside a router context).
+
+## Extends
+
+- [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md)\<[`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md), `TActor`\>
+
+## Type Parameters
+
+| Type Parameter                                 | Default type                |
+| ---------------------------------------------- | --------------------------- |
+| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
 
 ## Properties
 
-| Property                                  | Type                                                      | Defined in                                                                                                                                                                                                           |
-| ----------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | [`RoutableActor`](../type-aliases/RoutableActor.md)       | [packages/play-solid-router/src/play-router-provider.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L15) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                              | [packages/play-solid-router/src/play-router-provider.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L18) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                      | [packages/play-solid-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L16) |
-| <a id="property-router"></a> `router`     | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | [packages/play-solid-router/src/play-router-provider.tsx:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L17) |
+| Property                                  | Type                                                      | Description                                                                 | Inherited from                                                                                                                 | Defined in                                                                                                                                                                                       |
+| ----------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-actor"></a> `actor`       | `TActor`                                                  | The actor to sync with the router.                                          | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [packages/play-solid-router/src/create-play-router-provider.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/create-play-router-provider.tsx#L39) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                              | Renderer callback receives the same concrete actor type that was passed in. | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [packages/play-solid-router/src/create-play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/create-play-router-provider.tsx#L45) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                      | Bidirectional route map for state ID ↔ URL path lookups.                    | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [packages/play-solid-router/src/create-play-router-provider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/create-play-router-provider.tsx#L43) |
+| <a id="property-router"></a> `router`     | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | The router the bridge synchronizes with.                                    | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [packages/play-solid-router/src/create-play-router-provider.tsx:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/create-play-router-provider.tsx#L41) |

package/api/@xmachines/play-solid-router/interfaces/RouteMapOptions.md

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouteMapOptions
+
+# Interface: RouteMapOptions
+
+Defined in: [packages/play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L9)
+
+Options for `createRouteMap` and `createRouteMapFromTree`.
+
+## Properties
+
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                   |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [packages/play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/create-route-map.ts#L20) |

package/api/@xmachines/play-solid-router/interfaces/RouteMapping.md

@@ -1,14 +1,27 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouteMapping
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouteMapping
 
 # Interface: RouteMapping
 
-Defined in: [packages/play-solid-router/src/types.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/types.ts#L8)
+Defined in: [packages/play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L51)
 
-Mapping between state ID and URL path for SolidJS Router
+A single state ID ↔ path mapping entry.
+
+Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`RouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: RouteMapping = { stateId: "home", path: "/" };
+const paramMapping: RouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                              | Defined in                                                                                                                                                                           |
-| --------------------------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | SolidJS Router path pattern **Example** `'/', '/profile/:userId', '/settings/:section?'` | [packages/play-solid-router/src/types.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/types.ts#L19) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | XMachines state ID with # prefix **Example** `'#home', '#profile'`                       | [packages/play-solid-router/src/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/types.ts#L13) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                               |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [packages/play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [packages/play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/base-route-map.ts#L53) |

package/api/@xmachines/play-solid-router/interfaces/RouterBridge.md

@@ -1,12 +1,12 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouterBridge
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouterBridge
 
 # Interface: RouterBridge
 
-Defined in: packages/play-router/dist/types.d.ts:229
+Defined in: [packages/play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L341)
 
 RouterBridge interface for runtime infrastructure adapters
 
-Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
 the Actor. Infrastructure "bridges" to the Actor by observing its signals and
 managing its own lifecycle accordingly.
 
@@ -16,13 +16,13 @@ a unidirectional observation pattern. Infrastructure connects to observe Actor s
 
 ## Example
 
-TanStack Router bridge implementation
+Framework router bridge implementation
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
 import { Signal } from "@xmachines/play-signals";
 
-class TanStackRouterBridge implements RouterBridge {
+class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
@@ -44,7 +44,7 @@ class TanStackRouterBridge implements RouterBridge {
 
 ## See
 
-[RFC Play v1 - Invariant INV-04](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
 
 ## Methods
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: packages/play-router/dist/types.d.ts:245
+Defined in: [packages/play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L357)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: packages/play-router/dist/types.d.ts:260
+Defined in: [packages/play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-router/src/types.ts#L373)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-solid-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterBridgeConstructor
+
+# Type Alias: PlayRouterBridgeConstructor\<TRouter\>
+
+```ts
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
+```
+
+Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/create-play-router-provider.tsx#L25)
+
+Constructor shape a bridge class must satisfy to be used with
+`createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
+
+Bridges with a different constructor shape (e.g. `SolidRouterBridge`, which
+takes the hook results as separate arguments) are adapted with a thin
+subclass that repackages the `router` prop.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TRouter`      |
+
+## Parameters
+
+| Parameter  | Type                                      |
+| ---------- | ----------------------------------------- |
+| `router`   | `TRouter`                                 |
+| `actor`    | [`PlayActor`](../interfaces/PlayActor.md) |
+| `routeMap` | [`RouteMap`](../classes/RouteMap.md)      |
+
+## Returns
+
+[`RouterBridge`](../interfaces/RouterBridge.md)

package/api/@xmachines/play-solid-router/type-aliases/RoutableActor.md

@@ -1,9 +1,13 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RoutableActor
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RoutableActor
 
-# Type Alias: RoutableActor
+# ~~Type Alias: RoutableActor~~
 
 ```ts
-type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
+type RoutableActor = PlayActor;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L7)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L19)
+
+## Deprecated
+
+Use `PlayActor` from `@xmachines/play-router`. Will be removed in the next major version.

package/api/@xmachines/play-solid-router/type-aliases/SolidRouterHooks.md

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / SolidRouterHooks
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / SolidRouterHooks
 
 # Type Alias: SolidRouterHooks
 
@@ -6,46 +6,49 @@
 type SolidRouterHooks = object;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L8)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L37)
 
-## Properties
-
-### location
+The three Solid Router hook results that `PlayRouterProvider` and `SolidRouterBridge`
+require. Pass these directly from your component's hook calls:
 
-```ts
-location: object;
+```tsx
+const navigate = useNavigate(); // → SolidRouterHooks.navigate
+const location = useLocation(); // → SolidRouterHooks.location
+const params = useParams(); // → SolidRouterHooks.params
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L10)
-
-#### pathname
+- `navigate` — used to push URL changes when the actor's `currentRoute` changes.
+- `location` — `pathname` and `search` are read at `connect()` time for deep-link sync.
+  Subsequent pathname changes drive router→actor sync via `createEffect`.
+- `params` — Solid's pre-parsed path parameters for the current route segment. Used
+  directly in `extractParams()` to avoid re-parsing with URLPattern.
 
-```ts
-pathname: string;
-```
+## Properties
 
-#### search
+### location
 
 ```ts
-search: string;
+location: Location;
 ```
 
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L39)
+
 ---
 
 ### navigate
 
 ```ts
-navigate: ((path) => void) | ((path, ...args) => unknown);
+navigate: Navigator;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L9)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L38)
 
 ---
 
 ### params
 
 ```ts
-params: Record<string, string | undefined>;
+params: Params;
 ```
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L11)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L40)

package/api/@xmachines/play-solid-router/variables/PlayRouterProvider.md

@@ -0,0 +1,52 @@
+[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterProvider
+
+# Variable: PlayRouterProvider
+
+```ts
+const PlayRouterProvider: <TActor>(props) => any;
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-solid-router/src/play-router-provider.tsx#L92)
+
+Connects a `PlayerActor` to Solid Router, keeping actor state and browser URL
+in sync bidirectionally.
+
+The bridge is created synchronously at component evaluation time (Solid's
+execution model) and torn down via `onCleanup` when the component is disposed.
+Unlike React, prop stability is not a concern — Solid's `props` accessor is
+already reactive and the bridge is created once per component instance.
+
+The `router` prop must be obtained from Solid Router hooks in the parent component:
+
+```tsx
+function AppShell() {
+	const navigate = useNavigate();
+	const location = useLocation();
+	const params = useParams();
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			routeMap={routeMap}
+			router={{ navigate, location, params }}
+			renderer={(a) => <PlayRenderer actor={a} registry={registry} />}
+		/>
+	);
+}
+```
+
+## Type Parameters
+
+| Type Parameter                                               |
+| ------------------------------------------------------------ |
+| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) |
+
+## Parameters
+
+| Parameter | Type                                                                                                                                                 |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `props`   | [`PlayRouterProviderBaseProps`](../interfaces/PlayRouterProviderBaseProps.md)\<[`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md), `TActor`\> |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,270 @@
+[API](../../README.md) / @xmachines/play-svelte
+
+# @xmachines/play-svelte
+
+Svelte 5 renderer for the XMachines Play architecture — connects an actor to a `@xmachines/json-render-svelte` catalog-driven UI using Svelte 5 runes and TC39 Signals.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-svelte)
+
+Part of the [xmachines-js monorepo](../../README.md).
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-svelte
+```
+
+**Peer dependencies** (must be installed separately):
+
+```bash
+pnpm add svelte@^5.0.0 xstate@^5.31.0 @xstate/store@^3.17.0 \
+  @xmachines/json-render-core@^0.18.0 @xmachines/json-render-svelte@^0.18.0 @xmachines/json-render-xstate@^0.18.0
+```
+
+## 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 { 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 />
+</PlayUIProvider>
+```
+
+### Lower-level: ActorProvider
+
+Use `ActorProvider` directly when you need fine-grained control over rendering — for example, to wrap with a custom layout or inject the `@xmachines/json-render-svelte` providers individually:
+
+```svelte
+<script lang="ts">
+  import { ActorProvider } from "@xmachines/play-svelte";
+
+  let { actor, registryResult } = $props();
+</script>
+
+<ActorProvider {actor} {registryResult} fallback={loadingSnippet} onError={handleError}>
+  <!-- children rendered inside StateProvider tree -->
+  {@render children()}
+</ActorProvider>
+```
+
+### Accessing the actor from child components
+
+```ts
+import { getActorContext } from "@xmachines/play-svelte";
+
+// Inside a Svelte component that is a descendant of ActorProvider:
+const actor = getActorContext();
+actor.send({ type: "some.event" });
+```
+
+## API Summary
+
+### Components
+
+| 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 `@xmachines/json-render-svelte`. |
+
+### Functions
+
+| Function                           | Description                                                                                                                                                                                                             |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineRegistry(catalog, options)` | Creates a typed component registry. Wraps `@xmachines/json-render-svelte`'s `defineRegistry` with catalog-typed `params` on action handlers. Import from `@xmachines/play-svelte`, not `@xmachines/json-render-svelte`. |
+| `getActorContext()`                | Returns the `AnyPlayActor` 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`.                                                                                                                                                            |
+
+### Types
+
+| Type                       | Description                                                                                                                           |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `ActorProviderProps`       | Props for `<ActorProvider>`: `actor`, `registryResult`, optional `store`, `fallback` snippet, `onError`, `onRenderError`, `children`. |
+| `PlayUIProviderProps`      | Extends `ActorProviderProps` with optional `validationFunctions`, `navigate`, and `functions`.                                        |
+| `ViewContextValue`         | The view context shape provided by `ActorProvider` and consumed by `PlayRenderer`.                                                    |
+| `AnyPlayActor`             | `AbstractActor<AnyActorLogic> & Viewable` — the actor shape accepted by `ActorProvider` and `getActorContext`.                        |
+| `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.                                                                                                 |
+| `SetState`                 | State setter function type passed as the second argument to action handlers.                                                          |
+| `RenderErrorHandler`       | Callback `(error: unknown, elementType: string) => void` invoked when a catalog component throws.                                     |
+
+### Re-exports from `@xmachines/json-render-svelte`
+
+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";
+
+// Types
+import type {
+	JSONUIProviderProps,
+	BaseComponentProps,
+	ComponentFn,
+	ComponentContext,
+} from "@xmachines/play-svelte";
+```
+
+## Testing
+
+Run the test suite for this package:
+
+```bash
+pnpm --filter @xmachines/play-svelte test
+```
+
+Or from within the package directory:
+
+```bash
+pnpm test
+```
+
+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
+pnpm exec vitest --config vitest.browser.config.ts
+```
+
+**Coverage thresholds:** 80% lines, functions, branches, and statements (enforced via v8 provider).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+@xmachines/play-svelte - Svelte renderer for XMachines Play architecture
+
+Provides a provider/renderer split that mirrors @xmachines/json-render-svelte patterns:
+
+- ActorProvider: primitive escape-hatch (owns actor lifecycle, signal subscription,
+  per-view StateStore, onRenderError injection)
+- PlayUIProvider: batteries-included composite (ActorProvider + JsonUIProvider)
+- PlayRenderer: zero-prop leaf — reads getPlayViewContext() and renders Renderer
+
+Re-exports primitives from @xmachines/json-render-svelte so consumers import everything
+from @xmachines/play-svelte rather than @xmachines/json-render-svelte directly.
+
+## Interfaces
+
+- [ActorProviderProps](interfaces/ActorProviderProps.md)
+- [BaseComponentProps](interfaces/BaseComponentProps.md)
+- [ComponentContext](interfaces/ComponentContext.md)
+- [DefineRegistryOptions](interfaces/DefineRegistryOptions.md)
+- [PlayUIProviderProps](interfaces/PlayUIProviderProps.md)
+- [ViewContextValue](interfaces/ViewContextValue.md)
+
+## Type Aliases
+
+- [ActionFn](type-aliases/ActionFn.md)
+- [Actions](type-aliases/Actions.md)
+- [AnyPlayActor](type-aliases/AnyPlayActor.md)
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [JSONUIProviderProps](type-aliases/JSONUIProviderProps.md)
+- [PlayRenderer](type-aliases/PlayRenderer.md)
+- [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
+- [SetState](type-aliases/SetState.md)
+
+## Variables
+
+- [PlayRenderer](variables/PlayRenderer.md)
+
+## Functions
+
+- [defineRegistry](functions/defineRegistry.md)
+- [getActorContext](functions/getActorContext.md)
+- [getPlayViewContext](functions/getPlayViewContext.md)
+- [setActorContext](functions/setActorContext.md)
+
+## References
+
+### ActionProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### ActorProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### getBoundProp
+
+Renames and re-exports [JSONUIProviderProps](type-aliases/JSONUIProviderProps.md)
+
+---
+
+### getStateValue
+
+Renames and re-exports [JSONUIProviderProps](type-aliases/JSONUIProviderProps.md)
+
+---
+
+### JsonUIProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### PlayUIProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### Renderer
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### StateProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### ValidationProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)
+
+---
+
+### VisibilityProvider
+
+Renames and re-exports [PlayRenderer](variables/PlayRenderer.md)

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

@@ -0,0 +1,31 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / defineRegistry
+
+# Function: defineRegistry()
+
+```ts
+function defineRegistry<C>(catalog, options): DefineRegistryResult;
+```
+
+Defined in: [packages/play-svelte/src/define-registry.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-svelte/src/define-registry.ts#L154)
+
+Create a component registry, restoring catalog-typed `params` on action handlers.
+
+Drop-in replacement for `defineRegistry` from `@xmachines/json-render-svelte`. Import from
+`@xmachines/play-svelte` to get per-action param type inference for free.
+
+## Type Parameters
+
+| Type Parameter                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------ |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\> |
+
+## Parameters
+
+| Parameter | Type                                                                     | Description                                                                |
+| --------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `catalog` | `C`                                                                      | The json-render catalog defining component prop shapes and action schemas. |
+| `options` | [`DefineRegistryOptions`](../interfaces/DefineRegistryOptions.md)\<`C`\> | Registry options. `actions` entries receive params typed from the catalog. |
+
+## Returns
+
+`DefineRegistryResult`