@xmachines/docs 1.0.0-beta.32 → 1.0.0-beta.34

package/examples/@xmachines/play-react-demo/README.md

@@ -27,64 +27,71 @@ Then open `http://localhost:5173`.
 
 Use this order to understand the implementation:
 
-1. `src/main.tsx` mounts `<App />` inside `<StrictMode>`.
-2. `src/App.tsx` creates the actor via `definePlayer({ machine: authMachine })` inside `useMemo` so it is started once per mounted app.
-3. `defineRegistry(authCatalog, { components, actions })` builds the typed component registry from the shared catalog.
-4. `<PlayRenderer actor={actor} registry={registry} actions={...} />` observes actor view signals and renders the current component.
-5. A `useEffect` cleanup calls `actor.stop()` on unmount.
-6. Browser tests in `test/browser/` validate startup and interaction behavior.
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` creates the actor at module scope via `definePlayer({ machine: authMachine })()` — created once when the module is first evaluated.
+3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
+4. `<PlayUIProvider actor={actor} registryResult={registryResult}><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
+5. A `NavBar` component observes `actor` signals directly for nav visibility.
+6. `<DebugPanel actor={actor} />` shows live state, auth status, and current route.
+7. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```tsx
 // src/main.tsx (shape)
-createRoot(document.getElementById("root")!).render(
-	<StrictMode>
-		<App />
-	</StrictMode>,
-);
+createRoot(document.getElementById("root")!).render(<App />);
 ```
 
 ```tsx
 // src/App.tsx (shape)
-const createPlayer = definePlayer({ machine: authMachine });
-
-const { registry } = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-	},
-	actions: { login: async () => {}, logout: async () => {} },
-});
+const actor: AuthActor = definePlayer({ machine: authMachine })();
+actor.start();
 
 export function App() {
-	const actor = useMemo((): DemoActor => {
-		const a = createPlayer();
-		a.start();
-		return a;
-	}, []);
-
-	useEffect(
-		() => () => {
-			actor.stop();
-		},
-		[actor],
+	const registryResult = useMemo(
+		() =>
+			defineRegistry(authCatalog, {
+				components: {
+					Home,
+					About,
+					Contact,
+					Login,
+					Dashboard,
+					Overview,
+					Stats,
+					Profile,
+					Settings,
+					Navigation,
+					NavBar: NavBarView,
+				},
+				actions: {
+					login: async (args) =>
+						actor.send({
+							type: "auth.login",
+							username: assertNonNullable(args, "args").username,
+						}),
+					logout: async () => actor.send({ type: "auth.logout" }),
+					route: async (args) => {
+						const { to, params } = assertNonNullable(args, "args");
+						actor.send({
+							type: "play.route",
+							to,
+							...(params != null && { params }),
+						});
+					},
+				},
+			}),
+		[],
 	);
 
 	return (
 		<div className="demo-app" data-demo-shell>
+			<header className="demo-header">
+				<h1 className="demo-title">XMachines Play React Demo</h1>
+				<NavBar actor={actor} />
+			</header>
 			<main className="demo-content" data-demo-content>
-				<PlayRenderer
-					actor={actor}
-					registry={registry}
-					actions={{ login: "auth.login", logout: "auth.logout" }}
-				/>
+				<PlayUIProvider actor={actor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
 			</main>
 			<DebugPanel actor={actor} />
 		</div>
@@ -94,8 +101,8 @@ export function App() {
 
 ## Key Files
 
-- `src/main.tsx` - React entry point that mounts `<App />` inside `StrictMode`
-- `src/App.tsx` - actor lifecycle, registry construction, and `PlayRenderer` composition
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/App.tsx` - actor lifecycle, registry construction, and `PlayUIProvider` + `PlayRenderer` composition
 - `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.tsx` - browser-mode renderer coverage

package/examples/@xmachines/play-react-demo/functions/App.md

@@ -6,7 +6,7 @@
 function App(): Element;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/App.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/App.tsx#L36)
+Defined in: [packages/play-react/examples/demo/src/App.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/App.tsx#L36)
 
 ## Returns
 

package/examples/@xmachines/play-react-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-react/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-react-demo/variables/About.md

@@ -6,4 +6,4 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/About.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/About.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/About.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/About.tsx#L11)

package/examples/@xmachines/play-react-demo/variables/Contact.md

@@ -6,4 +6,4 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Contact.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Contact.tsx#L11)

package/examples/@xmachines/play-react-demo/variables/Dashboard.md

@@ -6,4 +6,4 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Dashboard.tsx#L15)
+Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Dashboard.tsx#L15)

package/examples/@xmachines/play-react-demo/variables/DebugPanel.md

@@ -8,4 +8,4 @@ const DebugPanel: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L6)
+Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L6)

package/examples/@xmachines/play-react-demo/variables/Home.md

@@ -6,4 +6,4 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Home.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Home.tsx#L11)

package/examples/@xmachines/play-react-demo/variables/Login.md

@@ -6,4 +6,4 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Login.tsx#L16)
+Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Login.tsx#L16)

package/examples/@xmachines/play-react-demo/variables/NavBar.md

@@ -8,4 +8,4 @@ const NavBar: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/NavBar.tsx#L13)
+Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/NavBar.tsx#L13)

package/examples/@xmachines/play-react-demo/variables/NavBarView.md

@@ -6,4 +6,4 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/NavBarView.tsx#L12)
+Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/NavBarView.tsx#L12)

package/examples/@xmachines/play-react-demo/variables/Navigation.md

@@ -6,4 +6,4 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Navigation.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Navigation.tsx#L11)

package/examples/@xmachines/play-react-demo/variables/Overview.md

@@ -6,4 +6,4 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Overview.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Overview.tsx#L11)

package/examples/@xmachines/play-react-demo/variables/Profile.md

@@ -6,4 +6,4 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Profile.tsx#L14)
+Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Profile.tsx#L14)

package/examples/@xmachines/play-react-demo/variables/Settings.md

@@ -6,4 +6,4 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Settings.tsx#L14)
+Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Settings.tsx#L14)

package/examples/@xmachines/play-react-demo/variables/Shell.md

@@ -10,4 +10,4 @@ const Shell: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Shell.tsx#L15)
+Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Shell.tsx#L15)

package/examples/@xmachines/play-react-demo/variables/Stats.md

@@ -6,4 +6,4 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/components/Stats.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/components/Stats.tsx#L11)

package/examples/@xmachines/play-react-demo/variables/authCatalog.md

@@ -169,4 +169,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-react/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-react/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-solid-demo/README.md

@@ -28,11 +28,12 @@ Then open `http://localhost:5173`.
 Use this order to understand the implementation:
 
 1. `src/main.tsx` mounts `<App />` to the DOM root via Solid's `render`.
-2. `src/App.tsx` calls `definePlayer({ machine: authMachine })` and starts the actor at module scope.
-3. `defineRegistry(authCatalog, { components, actions })` builds the typed component registry.
-4. `<PlayRenderer actor={actor} registry={registry} actions={...} />` observes actor view signals and renders the current component.
-5. `onCleanup` calls `actor.stop()` when the `App` component is disposed.
-6. Browser tests in `test/browser/` validate startup and interaction behavior.
+2. `src/App.tsx` creates the actor at module scope via `definePlayer({ machine: authMachine })()` and starts it.
+3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` inside `createMemo` — real async action handlers dispatching to `actor.send()`.
+4. `<PlayUIProvider actor={actor} registryResult={registryResult()}><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
+5. A `NavBar` component observes `actor` signals directly for nav visibility.
+6. `<DebugPanel actor={actor} />` shows live state, auth status, and current route.
+7. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```tsx
 // src/main.tsx (shape)
@@ -41,39 +42,57 @@ render(() => <App />, document.getElementById("app")!);
 
 ```tsx
 // src/App.tsx (shape)
-const createPlayer = definePlayer({ machine: authMachine });
-const actor = createPlayer() as AuthActor;
+const actor = definePlayer({ machine: authMachine })() as AuthActor;
 actor.start();
 
-const { registry } = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-	},
-	actions: { login: async () => {}, logout: async () => {} },
-});
-
 export function App() {
-	onCleanup(() => {
-		actor.stop();
-	});
+	const registryResult = createMemo(() =>
+		defineRegistry(authCatalog, {
+			components: {
+				Home,
+				About,
+				Contact,
+				Login,
+				Dashboard,
+				Overview,
+				Stats,
+				Profile,
+				Settings,
+				Navigation,
+				NavBar: NavBarView,
+			},
+			actions: {
+				login: async (args) =>
+					actor.send({
+						type: "auth.login",
+						username: assertNonNullable(args, "args").username,
+					}),
+				logout: async () => actor.send({ type: "auth.logout" }),
+				route: async (args) => {
+					const { to, params } = assertNonNullable(args, "args");
+					actor.send({
+						type: "play.route",
+						to,
+						...(params != null && { params }),
+					});
+				},
+			},
+		}),
+	);
 
 	return (
-		<main class="demo-content" data-demo-content>
-			<PlayRenderer
-				actor={actor}
-				registry={registry}
-				actions={{ login: "auth.login", logout: "auth.logout" }}
-			/>
-		</main>
+		<div class="demo-app" data-demo-shell>
+			<header class="demo-header">
+				<h1 class="demo-title">XMachines Play Solid Demo</h1>
+				<NavBar actor={actor} />
+			</header>
+			<main class="demo-content" data-demo-content>
+				<PlayUIProvider actor={actor} registryResult={registryResult()}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			</main>
+			<DebugPanel actor={actor} />
+		</div>
 	);
 }
 ```
@@ -81,7 +100,7 @@ export function App() {
 ## Key Files
 
 - `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
-- `src/App.tsx` - actor lifecycle, registry construction, and `PlayRenderer` composition
+- `src/App.tsx` - actor lifecycle, registry construction, and `PlayUIProvider` + `PlayRenderer` composition
 - `src/components/` - demo view components bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.tsx` - browser-mode renderer coverage

package/examples/@xmachines/play-solid-demo/functions/App.md

@@ -6,7 +6,7 @@
 function App(): Element;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/App.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/App.tsx#L34)
+Defined in: [packages/play-solid/examples/demo/src/App.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/App.tsx#L34)
 
 ## Returns
 

package/examples/@xmachines/play-solid-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-solid/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-solid-demo/variables/About.md

@@ -6,4 +6,4 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/About.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/About.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/About.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/About.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Contact.md

@@ -6,4 +6,4 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Contact.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Contact.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Contact.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Contact.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Dashboard.md

@@ -6,4 +6,4 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Dashboard.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Dashboard.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Dashboard.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/DebugPanel.md

@@ -8,4 +8,4 @@ const DebugPanel: Component<{
 }>;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L5)
+Defined in: [packages/play-solid/examples/demo/src/components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L5)

package/examples/@xmachines/play-solid-demo/variables/Home.md

@@ -6,4 +6,4 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Home.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Home.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Home.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Home.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Login.md

@@ -6,4 +6,4 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Login.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Login.tsx#L7)
+Defined in: [packages/play-solid/examples/demo/src/components/Login.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Login.tsx#L7)

package/examples/@xmachines/play-solid-demo/variables/NavBar.md

@@ -8,4 +8,4 @@ const NavBar: Component<{
 }>;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/NavBar.tsx#L28)
+Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/NavBar.tsx#L28)

package/examples/@xmachines/play-solid-demo/variables/NavBarView.md

@@ -6,7 +6,7 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/NavBar.tsx#L20)
+Defined in: [packages/play-solid/examples/demo/src/components/NavBar.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/NavBar.tsx#L20)
 
 Catalog-typed NavBar component for use in defineRegistry components map.
 Receives props from spec (isAuthenticated, username) and renders a static nav.

package/examples/@xmachines/play-solid-demo/variables/Navigation.md

@@ -6,4 +6,4 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Navigation.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Navigation.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Navigation.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Navigation.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Overview.md

@@ -6,4 +6,4 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Overview.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Overview.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Overview.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Overview.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Profile.md

@@ -6,4 +6,4 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Profile.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Profile.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Profile.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Profile.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Settings.md

@@ -6,4 +6,4 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Settings.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Settings.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Settings.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Settings.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/Shell.md

@@ -10,4 +10,4 @@ const Shell: Component<{
 }>;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Shell.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Shell.tsx#L8)
+Defined in: [packages/play-solid/examples/demo/src/components/Shell.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Shell.tsx#L8)

package/examples/@xmachines/play-solid-demo/variables/Stats.md

@@ -6,4 +6,4 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/components/Stats.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/components/Stats.tsx#L4)
+Defined in: [packages/play-solid/examples/demo/src/components/Stats.tsx:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/components/Stats.tsx#L4)

package/examples/@xmachines/play-solid-demo/variables/authCatalog.md

@@ -169,4 +169,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [packages/play-solid/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-solid/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-solid/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/examples/demo/src/catalog.ts#L5)

package/examples/@xmachines/play-svelte-demo/README.md

@@ -29,16 +29,15 @@ Use this order to understand the implementation:
 
 1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, and mounts `App.svelte` via Svelte's `mount`.
 2. The actor is passed to `App` as a prop.
-3. `src/App.svelte` calls `defineRegistry(authCatalog, { components, actions })` to build the typed component registry.
-4. `App.svelte` delegates to `Shell.svelte`, which renders `<PlayRenderer>` with the actor and registry.
-5. `Shell.svelte` also renders `<HeaderNav>` and `<DebugPanel>` — both observe actor signals directly.
+3. `src/App.svelte` calls `defineRegistry(authCatalog, { components, actions })` to build the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
+4. `App.svelte` delegates to `Shell.svelte`, passing both `actor` and `registryResult`.
+5. `Shell.svelte` renders `<PlayUIProvider><PlayRenderer /></PlayUIProvider>`, `<NavBar>`, and `<DebugPanel>` — the latter two observe actor signals directly.
 6. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
 7. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```ts
 // src/main.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine });
-const actor = createPlayer();
+const actor = definePlayer({ machine: authMachine })();
 actor.start();
 
 mount(App, { target: document.getElementById("app")!, props: { actor } });
@@ -47,30 +46,34 @@ mount(App, { target: document.getElementById("app")!, props: { actor } });
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	let { actor } = $props();
-	const { registry } = defineRegistry(authCatalog, {
-		components: { Home, About, Contact, Login, Dashboard, Overview, Stats, Profile, Settings, Navigation },
-		actions: { login: async () => {}, logout: async () => {} },
+	let { actor }: { actor: AuthActor } = $props();
+
+	const registryResult = defineRegistry(authCatalog, {
+		components: {
+			Home, About, Contact, Login, Dashboard,
+			Overview, Stats, Profile, Settings, Navigation,
+			NavBar: NavBarView,
+		},
+		actions: {
+			login: async (args) =>
+				actor.send({ type: "auth.login", username: assertNonNullable(args, "args").username }),
+			logout: async () => actor.send({ type: "auth.logout" }),
+			route: async (args) => {
+				const { to, params } = assertNonNullable(args, "args");
+				actor.send({ type: "play.route", to, ...(params != null && { params }) });
+			},
+		},
 	});
 </script>
 
-<Shell {actor} {registry} />
-```
-
-```svelte
-<!-- src/components/Shell.svelte (shape) -->
-<PlayRenderer
-	actor={props.actor}
-	registry={props.registry}
-	actions={{ login: "auth.login", logout: "auth.logout" }}
-/>
+<Shell {actor} {registryResult} />
 ```
 
 ## Key Files
 
 - `src/main.ts` - actor creation/start and Svelte app mount with actor as prop
 - `src/App.svelte` - registry construction, delegates rendering to `Shell.svelte`
-- `src/components/Shell.svelte` - shared shell with `PlayRenderer`, `HeaderNav`, and `DebugPanel`
+- `src/components/Shell.svelte` - shared shell with `PlayUIProvider` + `PlayRenderer`, `HeaderNav`, and `DebugPanel`
 - `src/components/` - demo view Svelte components bound to catalog component keys
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage

package/examples/@xmachines/play-svelte-spa-router-demo/README.md

@@ -31,7 +31,7 @@ Use this order to understand the implementation:
 2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
 3. `connectRouter` synchronizes hash URL changes with the actor via `play.route` events and reflects actor-approved routes back to the hash URL.
 4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
@@ -52,20 +52,18 @@ export function cleanupDemo(): void {
 ```svelte
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
-	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
-	import { actor, registry } from "./lib/router.js";
+	import { Shell } from "@xmachines/play-svelte-demo";
+	import { actor, registryResult } from "./lib/router.js";
 </script>
 
-<Shell {actor} {registry} />
+<Shell {actor} {registryResult} />
 ```
 
 ```svelte
-<!-- Shell.svelte — sending events (shape) -->
-<PlayRenderer
-	actor={props.actor}
-	registry={props.registry}
-	actions={{ login: "auth.login", logout: "auth.logout" }}
-/>
+<!-- Shell.svelte — rendering (shape) -->
+<PlayUIProvider actor={props.actor} registryResult={props.registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
 ## Key Files