@xmachines/docs 6.1.0 → 7.1.0

package/examples/multi-router-integration.md

@@ -21,151 +21,193 @@ Used by framework adapters that have a React/Solid/Vue provider context. The `Pl
 
 ### React + TanStack Router (`@xmachines/play-tanstack-react-router`)
 
-```typescript
+```tsx
 import { useEffect, useMemo } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
-import { defineRegistry } from "@xmachines/play-react";
-import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
+import { withView } from "@xmachines/play-xstate/view";
+import { PlayUIProvider, PlayRenderer, type DefineRegistryResult } from "@xmachines/play-react";
+import type { AnyStateMachine } from "xstate";
 
-const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
+// Your catalog, components and actions: defineRegistry(catalog, { components, actions })
+declare const registryResult: DefineRegistryResult;
 
-const { registry } = defineRegistry(authCatalog, {
-  components: { /* ...your components */ },
-  actions: { login: async () => {}, logout: async () => {}, /* ... */ },
+// The router needs `withRouting`, and the renderer needs `withView`.
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting, withView),
 });
 
 function createAppRuntime() {
-  const actor = createPlayer();
-  actor.start();
+	const actor = createPlayer();
+	actor.start();
 
-  const routeTree = extractMachineRoutes(authMachine);
-  const routeMap = createRouteMapFromTree(routeTree);
-  const router = createRouter({ routeTree: createRootRoute(), defaultPreload: "intent" });
+	const routeTree = extractMachineRoutes(appMachine);
+	const routeMap = createRouteMapFromTree(routeTree);
+	const router = createRouter({ routeTree: createRootRoute(), defaultPreload: "intent" });
 
-  return { actor, routeMap, router };
+	return { actor, routeMap, router };
 }
 
 export function App() {
-  const { actor, routeMap, router } = useMemo(createAppRuntime, []);
-
-  useEffect(() => () => { actor.stop(); }, [actor]);
-
-  return (
-    <PlayRouterProvider
-      actor={actor}
-      router={router}
-      routeMap={routeMap}
-      renderer={(currentActor, currentRouter) => (
-        <Shell actor={currentActor} router={currentRouter} registry={registry} />
-      )}
-    />
-  );
+	const { actor, routeMap, router } = useMemo(createAppRuntime, []);
+
+	useEffect(
+		() => () => {
+			actor.stop();
+		},
+		[actor],
+	);
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor) => (
+				<PlayUIProvider actor={currentActor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			)}
+		/>
+	);
 }
 ```
 
 ### React + React Router 7/8 (`@xmachines/play-react-router`)
 
-```typescript
+```tsx
+import { useEffect, useMemo } from "react";
 import { createBrowserRouter, RouterProvider } from "react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { PlayUIProvider, PlayRenderer, type DefineRegistryResult } from "@xmachines/play-react";
+import type { AnyStateMachine } from "xstate";
 
-const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
-
-function createAppRuntime() {
-  const actor = createPlayer();
-  actor.start();
-
-  const routeTree = extractMachineRoutes(authMachine);
-  const routeMap = createRouteMapFromTree(routeTree);
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
+// Your catalog, components and actions: defineRegistry(catalog, { components, actions })
+declare const registryResult: DefineRegistryResult;
 
-  // React Router requires route elements upfront — use a catch-all
-  let router!: ReturnType<typeof createBrowserRouter>;
-  function RoutedShell() {
-    return <Shell actor={actor} router={router} registry={registry} />;
-  }
-  router = createBrowserRouter([{ path: "*", element: <RoutedShell /> }]);
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 
-  return { actor, routeMap, router };
+function createAppRuntime() {
+	const actor = createPlayer();
+	actor.start();
+
+	const routeTree = extractMachineRoutes(appMachine);
+	const routeMap = createRouteMapFromTree(routeTree);
+
+	// React Router requires route elements upfront — use a catch-all
+	function RoutedShell() {
+		return (
+			<PlayUIProvider actor={actor} registryResult={registryResult}>
+				<PlayRenderer />
+			</PlayUIProvider>
+		);
+	}
+	const router = createBrowserRouter([{ path: "*", element: <RoutedShell /> }]);
+
+	return { actor, routeMap, router };
 }
 
 export default function App() {
-  const { actor, routeMap, router } = useMemo(createAppRuntime, []);
-
-  useEffect(() => () => { actor.stop(); }, [actor]);
-
-  return (
-    <PlayRouterProvider
-      actor={actor}
-      router={router}
-      routeMap={routeMap}
-      renderer={(currentActor, currentRouter) => (
-        <RouterProvider router={currentRouter} />
-      )}
-    />
-  );
+	const { actor, routeMap, router } = useMemo(createAppRuntime, []);
+
+	useEffect(
+		() => () => {
+			actor.stop();
+		},
+		[actor],
+	);
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(_, currentRouter) => <RouterProvider router={currentRouter} />}
+		/>
+	);
 }
 ```
 
 ### SolidJS + SolidJS Router (`@xmachines/play-solid-router`)
 
-```typescript
-import { Router, Route } from "@solidjs/router";
+```tsx
+import { Router, Route, useNavigate, useLocation, useParams } from "@solidjs/router";
 import { onCleanup } from "solid-js";
 import { PlayRouterProvider } from "@xmachines/play-solid-router";
 import { createRouteMap } from "@xmachines/play-router/xstate";
 import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { PlayUIProvider, PlayRenderer, type DefineRegistryResult } from "@xmachines/play-solid";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
+// Your catalog, components and actions: defineRegistry(catalog, { components, actions })
+declare const registryResult: DefineRegistryResult;
 
-const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer();
 actor.start();
 
-const routeTree = extractMachineRoutes(authMachine);
+const routeTree = extractMachineRoutes(appMachine);
 const routes = getRoutableRoutes(routeTree);
-const routeMap = createRouteMap(authMachine);
+const routeMap = createRouteMap(appMachine);
 
 // Layout rendered inside Router — has access to navigate/location/params hooks
 const Layout = () => {
-  const navigate = useNavigate();
-  const location = useLocation();
-  const params = useParams();
-
-  onCleanup(() => { actor.stop(); });
-
-  return (
-    <PlayRouterProvider
-      actor={actor}
-      routeMap={routeMap}
-      router={{ navigate, location, params }}
-      renderer={(currentActor, currentRouter) => (
-        <Shell actor={currentActor} router={currentRouter} registry={registry} />
-      )}
-    />
-  );
+	const navigate = useNavigate();
+	const location = useLocation();
+	const params = useParams();
+
+	onCleanup(() => {
+		actor.stop();
+	});
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			routeMap={routeMap}
+			router={{ navigate, location, params }}
+			renderer={(currentActor) => (
+				<PlayUIProvider actor={currentActor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			)}
+		/>
+	);
 };
 
 export default function App() {
-  return (
-    <Router root={Layout}>
-      {routes.map((route) => (
-        <Route path={route.fullPath} component={() => <div />} />
-      ))}
-    </Router>
-  );
+	return (
+		<Router root={Layout}>
+			{routes.map((route) => (
+				<Route path={route.fullPath} component={() => null} />
+			))}
+		</Router>
+	);
 }
 ```
 
 ### SolidJS + TanStack Solid Router (`@xmachines/play-tanstack-solid-router`)
 
-```typescript
+```tsx
 import { createRouter, createRootRoute, createRoute, RouterProvider } from "@tanstack/solid-router";
 import { onCleanup } from "solid-js";
 import { PlayRouterProvider } from "@xmachines/play-tanstack-solid-router";
@@ -173,42 +215,60 @@ import { createRouteMap } from "@xmachines/play-router/xstate";
 import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { PlayUIProvider, PlayRenderer, type DefineRegistryResult } from "@xmachines/play-solid";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
+// Your catalog, components and actions: defineRegistry(catalog, { components, actions })
+declare const registryResult: DefineRegistryResult;
 
-const createPlayer = definePlayer({ machine: authMachine, actor: compose(PlayerActor, withRouting) });
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer();
 actor.start();
 
-const routeTree = extractMachineRoutes(authMachine);
+const routeTree = extractMachineRoutes(appMachine);
 const routes = getRoutableRoutes(routeTree);
-const routeMap = createRouteMap(authMachine);
+const routeMap = createRouteMap(appMachine);
 
 const rootRoute = createRootRoute({ component: Layout });
 
 // Convert XMachines :param to TanStack $param format
 const tanstackRoutes = routes.map((route) => {
-  const tanstackPath = route.fullPath.replace(/:(\w+)/g, "$$$1");
-  return createRoute({ getParentRoute: () => rootRoute, path: tanstackPath, component: () => <div /> });
+	const tanstackPath = route.fullPath.replace(/:(\w+)/g, "$$$1");
+	return createRoute({
+		getParentRoute: () => rootRoute,
+		path: tanstackPath,
+		component: () => null,
+	});
 });
 
 const router = createRouter({ routeTree: rootRoute.addChildren(tanstackRoutes) });
 
 function Layout() {
-  onCleanup(() => { actor.stop(); });
-
-  return (
-    <PlayRouterProvider
-      actor={actor}
-      router={router}
-      routeMap={routeMap}
-      renderer={(currentActor, currentRouter) => (
-        <Shell actor={currentActor} router={currentRouter} registry={registry} />
-      )}
-    />
-  );
+	onCleanup(() => {
+		actor.stop();
+	});
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor) => (
+				<PlayUIProvider actor={currentActor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			)}
+		/>
+	);
 }
 
 export default function App() {
-  return <RouterProvider router={router} />;
+	return <RouterProvider router={router} />;
 }
 ```
 
@@ -226,16 +286,28 @@ export default function App() {
 </template>
 
 <script setup lang="ts">
-	import { h, inject } from "vue";
+	import { h } from "vue";
 	import { createRouter, createWebHistory } from "vue-router";
 	import { PlayRouterProvider } from "@xmachines/play-vue-router";
 	import { createRouteMap } from "@xmachines/play-router/xstate";
-	import { defineRegistry } from "@xmachines/play-vue";
-	import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
-
-	const actor = inject("actor");
+	import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+	import { withRouting } from "@xmachines/play-xstate/routing";
+	import { withView } from "@xmachines/play-xstate/view";
+	import { PlayUIProvider, PlayRenderer, type DefineRegistryResult } from "@xmachines/play-vue";
+	import type { AnyStateMachine } from "xstate";
+
+	declare const appMachine: AnyStateMachine; // your machine, with routes and views
+	// Your catalog, Vue SFC components and actions: defineRegistry(catalog, { components, actions })
+	declare const registryResult: DefineRegistryResult;
+
+	const createPlayer = definePlayer({
+		machine: appMachine,
+		actor: compose(PlayerActor, withRouting, withView),
+	});
+	const actor = createPlayer();
+	actor.start();
 
-	const routeMap = createRouteMap(authMachine);
+	const routeMap = createRouteMap(appMachine);
 
 	const router = createRouter({
 		history: createWebHistory(),
@@ -248,13 +320,7 @@ export default function App() {
 		],
 	});
 
-	const { registry } = defineRegistry(authCatalog, {
-		components: {/* ...your Vue SFC components */},
-		actions: { login: async () => {}, logout: async () => {} /* ... */ },
-	});
-
-	const renderShell = (currentActor, currentRouter) =>
-		h(Shell, { actor: currentActor, router: currentRouter, registry });
+	const renderShell = () => h(PlayUIProvider, { actor, registryResult }, () => h(PlayRenderer));
 </script>
 ```
 
@@ -271,20 +337,24 @@ import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
-import { createPlayUI, defineRegistry } from "@xmachines/play-dom";
-import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
+import { createPlayUI, type DefineRegistryResult } from "@xmachines/play-dom";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
+// Your catalog, components and actions: defineRegistry(catalog, { components, actions })
+declare const registryResult: DefineRegistryResult;
 
 // The router needs `withRouting`, and the renderer below needs `withView`.
 const createPlayer = definePlayer({
-	machine: authMachine,
+	machine: appMachine,
 	actor: compose(PlayerActor, withRouting, withView),
 });
 const actor = createPlayer();
 actor.start();
 
 // Router setup
-const routeTree = extractMachineRoutes(authMachine);
-const routeMap = createRouteMap(authMachine);
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMap(appMachine);
 const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
 
@@ -294,9 +364,6 @@ const router = createRouter({ routeTree, history });
 const disconnect = connectRouter({ actor, router, routeMap });
 
 // Renderer setup
-const registryResult = defineRegistry(authCatalog, {
-	components: {/* ...your DOM components */},
-});
 const mount = createPlayUI(registryResult);
 const disconnectRenderer = mount(actor, document.getElementById("app")!);
 
@@ -316,38 +383,40 @@ function teardown(): void {
 
 ```typescript
 // lib/router.ts
-import { defineRegistry } from "@xmachines/play-svelte";
-import { authCatalog, authMachine } from "@xmachines/play-actor-shared";
+import type { DefineRegistryResult } from "@xmachines/play-svelte";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
 import { connectRouter } from "@xmachines/play-sveltekit-router";
 import { createRouteMap } from "@xmachines/play-router/xstate";
-const createDemoPlayer = definePlayer({
-	machine: authMachine,
-	actor: compose(PlayerActor, withRouting, withView),
-});
+import type { AnyStateMachine } from "xstate";
 
-const { registry } = defineRegistry(authCatalog, {
-	components: {/* ...your Svelte components */},
-	actions: { login: async () => {}, logout: async () => {} /* ... */ },
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
+// Your catalog, Svelte components and actions: defineRegistry(catalog, { components, actions })
+export declare const registryResult: DefineRegistryResult;
+
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting, withView),
 });
 
-export const actor = createDemoPlayer();
+export const actor = createPlayer();
 actor.start();
 
-export const routeMap = createRouteMap(authMachine);
+export const routeMap = createRouteMap(appMachine);
 export const disconnectRouter = connectRouter({ actor, routeMap });
 ```
 
 ```html
 <!-- App.svelte -->
 <script lang="ts">
-	import Shell from "./Shell.svelte";
-	import { actor, registry } from "./lib/router.js";
+	import { PlayUIProvider, PlayRenderer } from "@xmachines/play-svelte";
+	import { actor, registryResult } from "./lib/router.js";
 </script>
 
-<Shell {actor} {registry} />
+<PlayUIProvider {actor} {registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
 ### Svelte SPA Router (`@xmachines/play-svelte-spa-router`)
@@ -359,17 +428,19 @@ import { createRouteMap } from "@xmachines/play-router/xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
-import { authMachine } from "@xmachines/play-actor-shared";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine, with routes and views
 
-const createDemoPlayer = definePlayer({
-	machine: authMachine,
+const createPlayer = definePlayer({
+	machine: appMachine,
 	actor: compose(PlayerActor, withRouting, withView),
 });
 
-export const actor = createDemoPlayer();
+export const actor = createPlayer();
 actor.start();
 
-export const routeMap = createRouteMap(authMachine);
+export const routeMap = createRouteMap(appMachine);
 export const disconnectRouter = connectRouter({ actor, routeMap });
 ```
 
@@ -384,6 +455,26 @@ The shape that motivates this is a URL such as `/:machineId/play/dashboard`. The
 `basePath` and `basePathParams` are **reactive props**. They need no stable reference, unlike `actor`, `router`, and `routeMap`, and a change moves the live bridge instead of rebuilding it:
 
 ```tsx
+import { useLoaderData } from "@tanstack/react-router";
+import {
+	PlayRouterProvider,
+	type RoutableActor,
+	type RouteMap,
+	type TanStackRouterInstance,
+} from "@xmachines/play-tanstack-react-router";
+import {
+	PlayUIProvider,
+	PlayRenderer,
+	type PlayUIProviderProps,
+	type DefineRegistryResult,
+} from "@xmachines/play-react";
+
+// The actor, the router, the route map, and the registry of the TanStack example above
+declare const actor: RoutableActor & PlayUIProviderProps["actor"];
+declare const router: TanStackRouterInstance;
+declare const routeMap: RouteMap;
+declare const registryResult: DefineRegistryResult;
+
 function PlayRoute() {
 	const { machineId } = useLoaderData({ from: "/$machineId/play/$" });
 
@@ -394,7 +485,11 @@ function PlayRoute() {
 			routeMap={routeMap} // unchanged — the route map stays machine-relative
 			basePath="/:machineId/play"
 			basePathParams={{ machineId }} // the loader resolved this already
-			renderer={(currentActor) => <Shell actor={currentActor} registry={registry} />}
+			renderer={(currentActor) => (
+				<PlayUIProvider actor={currentActor} registryResult={registryResult}>
+					<PlayRenderer />
+				</PlayUIProvider>
+			)}
 		/>
 	);
 }
@@ -409,6 +504,19 @@ function PlayRoute() {
 vanilla DOM adapter needs `router`, as it does in the example above:
 
 ```typescript
+import {
+	connectRouter,
+	type RoutableActor,
+	type RouteMap,
+	type VanillaRouter,
+} from "@xmachines/play-dom-router";
+
+// The actor, the router, and the route map of the vanilla DOM example above
+declare const actor: RoutableActor;
+declare const router: VanillaRouter;
+declare const routeMap: RouteMap;
+declare const machineId: string; // the host resolved this, for example in a loader
+
 const disconnect = connectRouter({
 	actor,
 	router, // required: @xmachines/play-dom-router reads its history
@@ -439,6 +547,10 @@ The prefix resolves in advance, because the bridge writes a real browser URL. It
 **The machine stays authoritative over its own params (INV-01).** `event.params` carries what the pattern of the machine declares and nothing else. The params of the prefix belong to the host, so they travel in no `play.route` event, and a host param that shares a name with one of the machine can shadow it never. Read the resolved mount from the bridge instead, where it cannot go stale:
 
 ```typescript
+import type { RouterBridgeBase } from "@xmachines/play-router";
+
+declare const bridge: RouterBridgeBase; // the bridge of any adapter
+
 bridge.basePath; // "/abc123/play"
 bridge.basePathParams; // { machineId: "abc123" }
 ```
@@ -458,6 +570,11 @@ Several machines can be alive together, each mounted at its own prefix, all shar
 `setBasePath()` moves **where** an actor is mounted, and never **which** actor is mounted. The actor, the route map, and its LRU cache all stay:
 
 ```typescript
+import type { RouterBridgeBase } from "@xmachines/play-router";
+
+declare const bridge: RouterBridgeBase; // the bridge of any adapter
+declare const machineId: string;
+
 // The host moved this actor from one region of its URL space to another.
 bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 ```
@@ -470,13 +587,17 @@ For a host router that declares real route objects, ask for the list — and dro
 
 ```typescript
 import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine, with routes
+declare const machineId: string; // "abc123", which the loader resolved
 
-const tree = extractMachineRoutes(authMachine);
+const tree = extractMachineRoutes(appMachine);
 
 // Concrete, for a route that the host adds after a loader resolved the mount
 getRouteMappings(tree, { basePath: "/:machineId/play", basePathParams: { machineId } });
 // [{ stateId: "home", path: "/abc123/play" },
-//  { stateId: "profile", path: "/abc123/play/profile/:userId" }, ...]
+//  { stateId: "profile", path: "/abc123/play/profile/:username" }, ...]
 
 // The pattern, for a static route declaration of the host
 getRouteMappings(tree, { basePath: "/:machineId/play" });