@xmachines/docs 1.0.0-beta.26 → 1.0.0-beta.28

package/examples/multi-router-integration.md

@@ -1,324 +1,406 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # Multi-Router Integration
 
-Learn how to integrate XMachines Play with the router adapters shipped in this monorepo.
+How to integrate XMachines Play with the 8 router adapters shipped in this monorepo.
 
 ## Overview
 
-The current router surface supports four integration modes with a consistent Play route-event model:
+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
-4. **Svelte** - `@xmachines/play-svelte` with either SvelteKit or SPA router adapters
+There are two integration patterns:
 
-React/TanStack integrations use a renderer-prop provider pattern. The lower-level adapters (`play-dom-router`, `play-sveltekit-router`, `play-svelte-spa-router`) use an explicit `connectRouter({ actor, routeMap })` bridge.
+| 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 (provider-based integrations)
+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 provider-based integrations
+  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 = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
-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";
 
-### 4. Svelte Import Split
+const createPlayer = definePlayer({ machine: authMachine });
 
-Svelte apps use the Play renderer and router adapters as separate imports:
+function createAppRuntime() {
+  const actor = createPlayer();
+  actor.start();
 
-```typescript
-import { PlayRenderer, defineRegistry } from "@xmachines/play-svelte";
-import {
-	connectRouter as connectSvelteKitRouter,
-	createRouteMap as createSvelteKitRouteMap,
-} from "@xmachines/play-sveltekit-router";
-import {
-	connectRouter as connectSvelteSpaRouter,
-	createRouteMap as createSvelteSpaRouteMap,
-} from "@xmachines/play-svelte-spa-router";
-```
+  const routeTree = extractMachineRoutes(authMachine);
+  const routeMap = createRouteMapFromTree(routeTree);
 
-- Use `@xmachines/play-svelte` for the Svelte renderer and component registry.
-- Use `@xmachines/play-sveltekit-router` when routing comes from SvelteKit navigation.
-- Use `@xmachines/play-svelte-spa-router` when routing comes from hash-based SPA navigation.
+  // 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 /> }]);
 
-Svelte does **not** use the React renderer-prop providers. Instead, connect the router adapter directly and render with `PlayRenderer`:
+  return { actor, routeMap, router };
+}
 
-```ts
-const routeMap = createSvelteKitRouteMap(machine);
-const disconnect = connectSvelteKitRouter({ actor, routeMap });
-```
+export default function App() {
+  const { actor, routeMap, router } = useMemo(createAppRuntime, []);
 
-## Mode 1: TanStack Router (React)
+  useEffect(() => () => { actor.stop(); }, [actor]);
 
-Complete integration with React and TanStack Router.
+  return (
+    <PlayRouterProvider
+      actor={actor}
+      router={router}
+      routeMap={routeMap}
+      renderer={(currentActor, currentRouter) => (
+        <RouterProvider router={currentRouter} />
+      )}
+    />
+  );
+}
+```
 
-For runnable implementations of these router integration patterns, see the [Examples Index](./README.md).
+### SolidJS + SolidJS Router (`@xmachines/play-solid-router`)
 
 ```typescript
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { createRouter, createMemoryHistory } from '@tanstack/react-router';
-import { PlayTanStackRouterProvider, createRouteMapFromTree } from '@xmachines/play-tanstack-react-router';
-import { extractMachineRoutes } from '@xmachines/play-router';
-import { PlayRenderer } from '@xmachines/play-react';
-import { definePlayer } from '@xmachines/play-xstate';
-
-// 1. Create actor
-const createPlayer = definePlayer({ machine, catalog });
+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();
 
-// 2. Create router from machine
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
-const router = createRouter({
-  routeTree,
-  history: createMemoryHistory()
-});
+const routeTree = extractMachineRoutes(authMachine);
+const routes = getRoutableRoutes(routeTree);
+const routeMap = createRouteMap(authMachine);
 
-// 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>
-  )
-};
+// 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(); });
 
-// 4. Render with provider + renderer prop
-function App() {
   return (
-    <PlayTanStackRouterProvider
+    <PlayRouterProvider
       actor={actor}
-      router={router}
-      renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
+      routeMap={routeMap}
+      router={{ navigate, location, params }}
+      renderer={(currentActor, currentRouter) => (
+        <Shell actor={currentActor} router={currentRouter} registry={registry} />
+      )}
     />
   );
-}
+};
 
-const root = createRoot(document.getElementById('app')!);
-root.render(<StrictMode><App /></StrictMode>);
+export default function App() {
+  return (
+    <Router root={Layout}>
+      {routes.map((route) => (
+        <Route path={route.fullPath} component={() => <div />} />
+      ))}
+    </Router>
+  );
+}
 ```
 
-### Benefits
-
-- Full React ecosystem support
-- Type-safe routing with TanStack Router
-- Browser history integration automatic
-- Signal reactivity via `PlayRenderer`
-
-## Mode 2: Vanilla Router (Preact, Solid, Vue)
-
-Framework-agnostic router for JSX-based frameworks.
+### SolidJS + TanStack Solid Router (`@xmachines/play-tanstack-solid-router`)
 
 ```typescript
-import {
-  connectRouter,
-  createBrowserHistory,
-  createRouter,
-} from '@xmachines/play-dom-router';
-import {
-  createRouteMap,
-  extractMachineRoutes,
-} 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 routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMap(routeTree);
-const history = createBrowserHistory({ window });
-const router = createRouter({ routeTree, history });
+const routeTree = extractMachineRoutes(authMachine);
+const routes = getRoutableRoutes(routeTree);
+const routeMap = createRouteMap(authMachine);
 
-// 3. Connect router with actor (bidirectional sync)
-const disconnect = connectRouter({ actor, router, routeMap });
+const rootRoute = createRootRoute({ component: Layout });
 
-history.subscribe(() => {
-  // Update your framework's router from the shared history state
-  myFrameworkRouter.push(history.location.pathname);
+// 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) });
 
-// Solid:
-import { Dynamic } from 'solid-js/web';
-<Dynamic component={components[view.component]} {...viewProps} />
+function Layout() {
+  onCleanup(() => { actor.stop(); });
 
-// Vue 3:
-import { h, resolveComponent } from 'vue';
-h(resolveComponent(view.component), viewProps)
+  return (
+    <PlayRouterProvider
+      actor={actor}
+      router={router}
+      routeMap={routeMap}
+      renderer={(currentActor, currentRouter) => (
+        <Shell actor={currentActor} router={currentRouter} registry={registry} />
+      )}
+    />
+  );
+}
+
+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 () => {} /* ... */ },
+	});
 
-- Works with any JSX framework
-- Manual control over routing integration
-- No React dependency
-- Same actor/signal API
+	const renderShell = (currentActor, currentRouter) =>
+		h(Shell, { actor: currentActor, router: currentRouter, registry });
+</script>
+```
 
-## Mode 3: Pure Browser (jQuery, Alpine, Vanilla JS)
+## Pattern 2: `connectRouter` Pattern
 
-Manual browser integration with no framework.
+Used by vanilla DOM and Svelte adapters. Call `connectRouter` directly after creating the actor — no provider component needed.
 
-```typescript
-import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+### Vanilla DOM (`@xmachines/play-dom-router`)
 
-// 1. Create actor
+```typescript
+import {
+	createBrowserHistory,
+	createRouter,
+	connectRouter,
+	createRouteMap,
+} from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { connectRenderer, defineRegistry } from "@xmachines/play-dom";
+import { authMachine, authCatalog } from "@xmachines/play-actor-shared";
+
+const createPlayer = definePlayer({ machine: authMachine });
 const actor = createPlayer();
 actor.start();
 
-// 2. Create browser history and router
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMap(routeTree);
+// Router setup
+const routeTree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMap(authMachine);
 const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
 
-// 3. Connect router with actor (handles all bidirectional sync)
+// 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. Manual rendering — subscribe to actor signals
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		const view = actor.currentView.get();
-		renderView(view);
-		watcher.watch(actor.currentView);
-	});
+// Renderer setup
+const { registry } = defineRegistry(authCatalog, {
+	components: {
+		/* ...your DOM components */
+	},
+});
+const disconnectRenderer = connectRenderer({
+	actor,
+	registry,
+	container: document.getElementById("app")!,
 });
-watcher.watch(actor.currentView);
-renderView(actor.currentView.get());
-
-function renderView(view) {
-	// 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>
-    `;
-	}
-}
-
-// 5. Manual event handlers
-function navigateToAbout() {
-	actor.send({ type: "play.route", to: "/about" });
-}
-
-function navigateToHome() {
-	actor.send({ type: "play.route", to: "/" });
-}
 
-// 6. Cleanup on unload
+// Cleanup
 window.addEventListener("beforeunload", () => {
 	disconnect();
 	router.destroy();
-	watcher.unwatch(actor.currentView);
+	disconnectRenderer();
+	actor.stop();
 });
 ```
 
-### Benefits
+### SvelteKit (`@xmachines/play-sveltekit-router`)
+
+```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 });
+
+const { registry } = defineRegistry(authCatalog, {
+	components: {
+		/* ...your Svelte components */
+	},
+	actions: { login: async () => {}, logout: async () => {} /* ... */ },
+});
+
+export const actor = createDemoPlayer();
+actor.start();
+
+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} />
+```
+
+### 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)        | `createRouter()` + `createRouteMap()` | `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 | `connectRenderer`, `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
-- **[Examples Index](./README.md)** - Complete catalog of runnable demos and example guides
+- **[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](../api/@xmachines/play-tanstack-react-router/README.md) - TanStack integration details
-- [play-react README](../api/@xmachines/play-react/README.md) - React renderer documentation
-- [play-router README](../api/@xmachines/play-router/README.md) - Framework-agnostic routing (route tree, route map, router bridge)
-- [play-dom-router README](../api/@xmachines/play-dom-router/README.md) - Vanilla DOM bindings (`createBrowserHistory`, `createRouter`, `connectRouter`)
-- [Play RFC](../rfc/play.md) - Complete specification
+- [Play RFC](../rfc/play.md) — Complete architectural specification
+- [play-router README](../api/@xmachines/play-router/README.md) — Route extraction and route maps
+- [play-dom-router README](../api/@xmachines/play-dom-router/README.md) — Vanilla DOM router adapter