@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/examples/multi-router-integration.md

@@ -1,277 +1,395 @@
-# Multi-Router Integration - Renderer Prop Pattern
+# Multi-Router Integration
 
-Learn how to integrate Play Architecture with three router modes using the unified renderer prop pattern introduced in
+How to integrate XMachines Play with the 8 router adapters shipped in this monorepo.
 
 ## Overview
 
-introduces a unified multi-router architecture supporting three integration modes with consistent API:
+XMachines provides router adapters for every major JavaScript framework. All adapters implement the same **Actor Authority** invariant — the state machine guards control navigation, and the router passively observes `actor.currentRoute`.
 
-1. **TanStack Router** - React + TanStack Router with full feature set
-2. **Vanilla Router** - JSX frameworks (Preact, Solid, Vue) with framework-agnostic router
-3. **Pure Browser** - Manual integration for jQuery, Alpine, vanilla JS
+There are two integration patterns:
 
-All modes use the **renderer prop pattern** where providers receive an `actor` and `router`, then pass a `renderer` function (not children).
+| Pattern                     | Used by                                                                        | Key API                                                       |
+| --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| **Provider pattern**        | React (TanStack, React Router), SolidJS (TanStack, SolidJS Router), Vue Router | `<PlayRouterProvider actor router routeMap renderer={...} />` |
+| **`connectRouter` pattern** | Vanilla DOM, SvelteKit, Svelte SPA Router                                      | `connectRouter({ actor, routeMap })`                          |
 
-## Key Concepts
+## Pattern 1: Provider Pattern
 
-### 1. Renderer Prop Pattern
+Used by framework adapters that have a React/Solid/Vue provider context. The `PlayRouterProvider` owns the bridge lifecycle and calls a `renderer` prop with the current actor and router.
 
-All providers use a `renderer` prop that receives the actor and returns a ReactNode:
+### React + TanStack Router (`@xmachines/play-tanstack-react-router`)
 
 ```typescript
-<PlayTanStackRouterProvider
-  actor={actor}
-  router={router}
-  renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
-/>
-```
+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";
+import { definePlayer } from "@xmachines/play-xstate";
+import { defineRegistry } from "@xmachines/play-react";
+import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
+
+const createPlayer = definePlayer({ machine: authMachine });
+
+const { registry } = defineRegistry(authCatalog, {
+  components: { /* ...your components */ },
+  actions: { login: async () => {}, logout: async () => {}, /* ... */ },
+});
 
-**Why renderer prop instead of children?**
+function createAppRuntime() {
+  const actor = createPlayer();
+  actor.start();
 
-- Explicit dependency injection (actor passed to renderer function)
-- Type-safe integration (renderer function signature enforced)
-- Consistent pattern across all three modes
+  const routeTree = extractMachineRoutes(authMachine);
+  const routeMap = createRouteMapFromTree(routeTree);
+  const router = createRouter({ routeTree: createRootRoute(), defaultPreload: "intent" });
 
-### 2. RouteMap as Explicit Prop
+  return { actor, routeMap, router };
+}
 
-All providers require `routeMap` as an explicit prop. Routers fundamentally don't know about Play state IDs — the map bridges the gap:
+export function App() {
+  const { actor, routeMap, router } = useMemo(createAppRuntime, []);
 
-```typescript
-const routeTree = createPlayRouter({ machine });
-const router = createRouter({ routeTree, history: createMemoryHistory() });
-
-<PlayTanStackRouterProvider
-  actor={actor}
-  router={router}
-  routeMap={routeMap}  // Explicit mapping
-  renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
-/>
-```
+  useEffect(() => () => { actor.stop(); }, [actor]);
 
-### 3. Provider Composition Pattern
+  return (
+    <PlayRouterProvider
+      actor={actor}
+      router={router}
+      routeMap={routeMap}
+      renderer={(currentActor, currentRouter) => (
+        <Shell actor={currentActor} router={currentRouter} registry={registry} />
+      )}
+    />
+  );
+}
+```
 
-Providers wrap external providers (like TanStack's `RouterProvider`) and add Play integration layer:
+### React + React Router v7 (`@xmachines/play-react-router`)
 
 ```typescript
-// Provider wraps TanStack RouterProvider
-<RouterProvider router={router}>
-  {/* Play integration layer */}
-  {renderer(actor)}
-</RouterProvider>
-```
+import { createBrowserRouter, RouterProvider } from "react-router";
+import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer } from "@xmachines/play-xstate";
 
-## Mode 1: TanStack Router (React)
+const createPlayer = definePlayer({ machine: authMachine });
 
-Complete integration with React and TanStack Router.
+function createAppRuntime() {
+  const actor = createPlayer();
+  actor.start();
 
-See [multi-router-example.ts](./src/multi-router-example.ts) for runnable example.
+  const routeTree = extractMachineRoutes(authMachine);
+  const routeMap = createRouteMapFromTree(routeTree);
 
-```typescript
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { createRouter, createMemoryHistory } from '@tanstack/react-router';
-import { createPlayRouter, PlayTanStackRouterProvider } from '@xmachines/play-tanstack-react-router';
-import { PlayRenderer } from '@xmachines/play-react';
-import { definePlayer } from '@xmachines/play-xstate';
-
-// 1. Create actor
-const createPlayer = definePlayer({ machine, catalog });
-const actor = createPlayer();
+  // 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 /> }]);
 
-// 2. Create router from machine
-const routeTree = createPlayRouter({ machine });
-const router = createRouter({
-  routeTree,
-  history: createMemoryHistory()
-});
+  return { actor, routeMap, router };
+}
 
-// 3. Define React components
-const components = {
-  HomeView: ({ send }) => (
-    <div>
-      <h1>Home</h1>
-      <button onClick={() => send({ type: 'play.route', to: '/about' })}>
-        Go to About
-      </button>
-    </div>
-  ),
-  AboutView: ({ send }) => (
-    <div>
-      <h1>About</h1>
-      <button onClick={() => send({ type: 'play.route', to: '/' })}>
-        Go to Home
-      </button>
-    </div>
-  )
-};
+export default function App() {
+  const { actor, routeMap, router } = useMemo(createAppRuntime, []);
+
+  useEffect(() => () => { actor.stop(); }, [actor]);
 
-// 4. Render with provider + renderer prop
-function App() {
   return (
-    <PlayTanStackRouterProvider
+    <PlayRouterProvider
       actor={actor}
       router={router}
-      renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
+      routeMap={routeMap}
+      renderer={(currentActor, currentRouter) => (
+        <RouterProvider router={currentRouter} />
+      )}
     />
   );
 }
-
-const root = createRoot(document.getElementById('app')!);
-root.render(<StrictMode><App /></StrictMode>);
 ```
 
-### Benefits
+### SolidJS + SolidJS Router (`@xmachines/play-solid-router`)
+
+```typescript
+import { Router, Route } from "@solidjs/router";
+import { onCleanup } from "solid-js";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-solid-router";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const routeTree = extractMachineRoutes(authMachine);
+const routes = getRoutableRoutes(routeTree);
+const routeMap = createRouteMap(authMachine);
+
+// Layout rendered inside Router — has access to navigate/location/params hooks
+const Layout = () => {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const params = useParams();
 
-- Full React ecosystem support
-- Type-safe routing with TanStack Router
-- Browser history integration automatic
-- Signal reactivity via `PlayRenderer`
+  onCleanup(() => { actor.stop(); });
 
-## Mode 2: Vanilla Router (Preact, Solid, Vue)
+  return (
+    <PlayRouterProvider
+      actor={actor}
+      routeMap={routeMap}
+      router={{ navigate, location, params }}
+      renderer={(currentActor, currentRouter) => (
+        <Shell actor={currentActor} router={currentRouter} registry={registry} />
+      )}
+    />
+  );
+};
 
-Framework-agnostic router for JSX-based frameworks.
+export default function App() {
+  return (
+    <Router root={Layout}>
+      {routes.map((route) => (
+        <Route path={route.fullPath} component={() => <div />} />
+      ))}
+    </Router>
+  );
+}
+```
+
+### SolidJS + TanStack Solid Router (`@xmachines/play-tanstack-solid-router`)
 
 ```typescript
-import { createPlayRouter, connectRouter } from '@xmachines/play-router';
-import { definePlayer } from '@xmachines/play-xstate';
+import { createRouter, createRootRoute, createRoute, RouterProvider } from "@tanstack/solid-router";
+import { onCleanup } from "solid-js";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-solid-router";
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+import { definePlayer } from "@xmachines/play-xstate";
 
-// 1. Create actor
-const createPlayer = definePlayer({ machine, catalog });
+const createPlayer = definePlayer({ machine: authMachine });
 const actor = createPlayer();
+actor.start();
 
-// 2. Create framework-agnostic router
-const router = createPlayRouter({ machine });
+const routeTree = extractMachineRoutes(authMachine);
+const routes = getRoutableRoutes(routeTree);
+const routeMap = createRouteMap(authMachine);
 
-// 3. Connect router with manual integration
-const disconnect = connectRouter(actor, {
-  onNavigate: (path) => {
-    // Update your framework's router
-    myFrameworkRouter.push(path);
-  }
+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 /> });
 });
 
-// 4. Framework-specific rendering
-// Preact:
-import { h } from 'preact';
-const view = actor.currentView.get();
-render(h(components[view.component], viewProps), container);
+const router = createRouter({ routeTree: rootRoute.addChildren(tanstackRoutes) });
+
+function Layout() {
+  onCleanup(() => { actor.stop(); });
 
-// Solid:
-import { Dynamic } from 'solid-js/web';
-<Dynamic component={components[view.component]} {...viewProps} />
+  return (
+    <PlayRouterProvider
+      actor={actor}
+      router={router}
+      routeMap={routeMap}
+      renderer={(currentActor, currentRouter) => (
+        <Shell actor={currentActor} router={currentRouter} registry={registry} />
+      )}
+    />
+  );
+}
 
-// Vue 3:
-import { h, resolveComponent } from 'vue';
-h(resolveComponent(view.component), viewProps)
+export default function App() {
+  return <RouterProvider router={router} />;
+}
 ```
 
-### Benefits
+### Vue + Vue Router (`@xmachines/play-vue-router`)
+
+```html
+<!-- App.vue -->
+<template>
+	<PlayRouterProvider
+		:actor="actor"
+		:route-map="routeMap"
+		:router="router"
+		:renderer="renderShell"
+	/>
+</template>
+
+<script setup lang="ts">
+	import { h, inject } from "vue";
+	import { createRouter, createWebHistory } from "vue-router";
+	import { PlayRouterProvider, createRouteMap } from "@xmachines/play-vue-router";
+	import { defineRegistry } from "@xmachines/play-vue";
+	import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
+
+	const actor = inject("actor");
+
+	const routeMap = createRouteMap(authMachine);
+
+	const router = createRouter({
+		history: createWebHistory(),
+		routes: [
+			{
+				path: "/:pathMatch(.*)*",
+				name: "xmachines-play",
+				component: { render: () => h("div") },
+			},
+		],
+	});
+
+	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 });
+</script>
+```
 
-- Works with any JSX framework
-- Manual control over routing integration
-- No React dependency
-- Same actor/signal API
+## Pattern 2: `connectRouter` Pattern
 
-## Mode 3: Pure Browser (jQuery, Alpine, Vanilla JS)
+Used by vanilla DOM and Svelte adapters. Call `connectRouter` directly after creating the actor — no provider component needed.
 
-Manual browser integration with no framework.
+### Vanilla DOM (`@xmachines/play-dom-router`)
 
 ```typescript
-import { createPlayRouter, connectRouter } from "@xmachines/play-router";
-
-// 1. Create actor
+import {
+	createBrowserHistory,
+	createRouter,
+	connectRouter,
+	createRouteMap,
+} from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { createPlayUI, defineRegistry } from "@xmachines/play-dom";
+import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
+
+const createPlayer = definePlayer({ machine: authMachine });
 const actor = createPlayer();
+actor.start();
 
-// 2. Connect router with browser integration
-const disconnect = connectRouter(actor, {
-	onNavigate: (path) => {
-		// Update browser history
-		window.history.pushState({}, "", path);
-		renderView();
-	},
-});
+// Router setup
+const routeTree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMap(authMachine);
+const history = createBrowserHistory({ window });
+const router = createRouter({ routeTree, history });
 
-// 3. Manual rendering
-function renderView() {
-	const view = actor.currentView.get();
-
-	// Vanilla JS rendering
-	if (view.component === "HomeView") {
-		document.getElementById("app").innerHTML = `
-      <h1>Home</h1>
-      <button onclick="navigateToAbout()">Go to About</button>
-    `;
-	} else if (view.component === "AboutView") {
-		document.getElementById("app").innerHTML = `
-      <h1>About</h1>
-      <button onclick="navigateToHome()">Go to Home</button>
-    `;
-	}
-}
+// connectRouter handles bidirectional sync:
+// - actor.currentRoute changes → browser URL updated
+// - browser URL changes → play.route event sent to actor
+const disconnect = connectRouter({ actor, router, routeMap });
 
-// 4. Listen to browser back/forward
-window.addEventListener("popstate", () => {
-	const path = window.location.pathname;
-	actor.send({ type: "play.route", to: path });
+// Renderer setup
+const registryResult = defineRegistry(authCatalog, {
+	components: {/* ...your DOM components */},
+});
+const mount = createPlayUI(registryResult);
+const disconnectRenderer = mount(actor, document.getElementById("app")!);
+
+// Cleanup
+window.addEventListener("beforeunload", () => {
+	disconnect();
+	router.destroy();
+	disconnectRenderer();
+	actor.stop();
 });
+```
 
-// 5. Manual event handlers
-function navigateToAbout() {
-	actor.send({ type: "play.route", to: "/about" });
-}
+### SvelteKit (`@xmachines/play-sveltekit-router`)
 
-function navigateToHome() {
-	actor.send({ type: "play.route", to: "/" });
-}
+```typescript
+// lib/router.ts
+import { defineRegistry } from "@xmachines/play-svelte";
+import { authCatalog, authMachine } from "@xmachines/play-actor-shared";
+import { definePlayer } from "@xmachines/play-xstate";
+import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
+
+const createDemoPlayer = definePlayer({ machine: authMachine });
 
-// Start
+const { registry } = defineRegistry(authCatalog, {
+	components: {/* ...your Svelte components */},
+	actions: { login: async () => {}, logout: async () => {} /* ... */ },
+});
+
+export const actor = createDemoPlayer();
 actor.start();
-renderView();
+
+export const routeMap = createRouteMap(authMachine);
+export const disconnectRouter = connectRouter({ actor, routeMap });
+```
+
+```html
+<!-- App.svelte -->
+<script lang="ts">
+	import Shell from "./Shell.svelte";
+	import { actor, registry } from "./lib/router.js";
+</script>
+
+<Shell {actor} {registry} />
 ```
 
-### Benefits
+### Svelte SPA Router (`@xmachines/play-svelte-spa-router`)
+
+```typescript
+// lib/router.ts — identical pattern to SvelteKit, different import
+import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { authMachine } from "@xmachines/play-actor-shared";
+
+const createDemoPlayer = definePlayer({ machine: authMachine });
+
+export const actor = createDemoPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+export const disconnectRouter = connectRouter({ actor, routeMap });
+```
 
-- No framework dependency at all
-- Maximum control and flexibility
-- Works with jQuery, Alpine.js, HTMX, etc.
-- Signals available via `actor.currentView.get()`
+## Adapter Summary
 
-## Provider API Parallelism
+| Package                                 | Framework             | Pattern         | Key Import                                                                |
+| --------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
+| `@xmachines/play-dom-router`            | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
+| `@xmachines/play-react-router`          | React Router v7       | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| `@xmachines/play-tanstack-react-router` | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| `@xmachines/play-solid-router`          | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| `@xmachines/play-tanstack-solid-router` | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| `@xmachines/play-vue-router`            | Vue Router            | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| `@xmachines/play-sveltekit-router`      | SvelteKit             | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
+| `@xmachines/play-svelte-spa-router`     | Svelte SPA Router     | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
 
-All three modes follow the same pattern:
+## Renderer Packages
 
-| Concept     | TanStack Mode                      | Vanilla Mode                         | Pure Browser Mode          |
-| ----------- | ---------------------------------- | ------------------------------------ | -------------------------- |
-| Actor       | `createPlayer()`                   | `createPlayer()`                     | `createPlayer()`           |
-| Router      | `createRouter()` (TanStack)        | `createPlayRouter()`                 | `connectRouter()`          |
-| Integration | `<PlayTanStackRouterProvider>`     | Manual via `onNavigate` callback     | Manual + `window.popstate` |
-| Rendering   | `<PlayRenderer>` via renderer prop | Framework-specific (h, Dynamic, etc) | `innerHTML` or DOM API     |
-| Events      | Component `onClick` → `send()`     | Same                                 | Same                       |
-| Signals     | Observed by `useSignalEffect`      | Manual `actor.currentView.get()`     | Same                       |
+Each framework also has a companion renderer package for the view layer:
 
-The API parallelism ensures consistent patterns regardless of mode.
+| Package                  | Framework   | Key API                                            |
+| ------------------------ | ----------- | -------------------------------------------------- |
+| `@xmachines/play-dom`    | Vanilla DOM | `createPlayUI`, `createRenderer`, `defineRegistry` |
+| `@xmachines/play-react`  | React       | `PlayRenderer`, `defineRegistry`                   |
+| `@xmachines/play-solid`  | SolidJS     | `PlayRenderer`, `defineRegistry`                   |
+| `@xmachines/play-vue`    | Vue 3       | `PlayRenderer`, `defineRegistry`                   |
+| `@xmachines/play-svelte` | Svelte 5    | `PlayRenderer`, `defineRegistry`                   |
 
 ## Architectural Invariants
 
-All three modes preserve the 5 architectural invariants:
+All adapters preserve the 5 architectural invariants:
 
-1. **Actor Authority (INV-01):** Guards validate all navigation across all modes
+1. **Actor Authority (INV-01):** Machine guards validate all navigation
 2. **Strict Separation (INV-02):** Business logic (machine) has zero framework imports
-3. **Signal-Only Reactivity (INV-05):** TC39 Signals work identically in all modes
+3. **State-Driven Reset (INV-03):** Browser back/forward sends `play.route` events to actor
 4. **Passive Infrastructure (INV-04):** Router observes actor, never decides
-5. **State-Driven Reset (INV-03):** Browser back/forward sends events to actor
+5. **Signal-Only Reactivity (INV-05):** TC39 Signals work identically in all adapters
 
 ## Next Steps
 
-- **[Routing Patterns](./routing-patterns.md)** - Learn play.route events with parameters
-- **[Integration Example](./src/integration-example.ts)** - Complete authentication flow
-- **[React + TanStack Router Demo](../../packages/play-tanstack-react-router/examples/demo-app/)** - Production example using TanStack mode
-- **[Vue Router Demo](../../packages/play-vue-router/examples/demo/)** - Vue Composition API integration
-- **[SolidJS Router Demo](../../packages/play-solidjs-router/examples/demo/)** - Solid signals integration
+- **[Routing Patterns](./routing-patterns.md)** — `meta.route`, `play.route`, `always` guards
+- **[Examples Index](./README.md)** — Complete catalog of runnable demos
 
 ## Learn More
 
-- [play-tanstack-router README](../../packages/play-tanstack-react-router/README.md) - TanStack integration details
-- [play-react README](../../packages/play-react/README.md) - React renderer documentation
-- [play-router README](../../packages/play-router/README.md) - Framework-agnostic routing
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md) - Complete specification
+- [Play RFC](../rfc/play.md) — Complete architectural specification
+- [play-router](../api/@xmachines/play-router/README.md) — Route extraction and route maps
+- [play-dom-router](../api/@xmachines/play-dom-router/README.md) — Vanilla DOM router adapter