@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

package/api/@xmachines/play-sveltekit-router/interfaces/PlayRouteEvent.md

@@ -0,0 +1,129 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: [play-router/src/types.ts:244](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L244)
+
+Enhanced routing event with parameter and query support
+
+Unified routing event used throughout the Play architecture. Supports parameter-aware
+navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
+user navigation intent that the Actor evaluates through guards. Infrastructure proposes
+via `play.route` events, Actor decides via state machine transitions.
+
+**Browser Navigation Flow:**
+
+1. Browser fires `popstate`
+2. Router adapter resolves URL to route target
+3. Adapter sends `PlayRouteEvent` to Actor
+4. Actor validates transition via state machine guards
+
+## Param
+
+**type**
+
+Event discriminator (always "play.route")
+
+## Param
+
+**to**
+
+Target state ID with # prefix (e.g., '#home', '#profile')
+
+## Param
+
+**params**
+
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+
+## Param
+
+**query**
+
+Query parameters only (isolated from path params)
+
+## Param
+
+**match**
+
+Full URLPattern match result for debugging/observability (optional)
+
+## Examples
+
+Combining base and routing events
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+type AppEvent = PlayEvent | PlayRouteEvent;
+```
+
+Basic navigation to a route
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#home",
+};
+actor.send(event);
+```
+
+Navigation with route parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#profile",
+	params: { userId: "123" },
+};
+actor.send(event);
+// Resolves to route: /profile/123
+```
+
+Navigation with query parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#settings",
+	params: { section: "profile" }, // Path-only route parameter
+	query: { tab: "security" }, // Query-only
+};
+actor.send(event);
+// Resolves to route: /settings/profile?tab=security
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.md)
+
+## Remarks
+
+Use `play.route` when you need parameter-aware navigation with the `route: {}`
+config pattern on your state machine nodes. The `match` field exposes the full
+URLPatternResult for advanced use cases (debugging, pattern analysis).
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
+| -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L249) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:247](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L247) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L248) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:246](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L246) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:245](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L245) |

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

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

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

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

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

@@ -0,0 +1,104 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: [play-router/src/types.ts:360](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L360)
+
+RouterBridge interface for runtime infrastructure adapters
+
+Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
+the Actor. Infrastructure "bridges" to the Actor by observing its signals and
+managing its own lifecycle accordingly.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
+a unidirectional observation pattern. Infrastructure connects to observe Actor signals
+(currentRoute, currentView, state) and reflects changes without making state decisions.
+
+## Example
+
+Framework router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class MyRouterBridge implements RouterBridge {
+	private watcher: Signal.Watcher | null = null;
+
+	async connect(): Promise<void> {
+		// Start observing actor.currentRoute signal
+		this.watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			if (route) router.navigate(route);
+		});
+		this.watcher.watch(actor.currentRoute);
+	}
+
+	async disconnect(): Promise<void> {
+		// Stop observing, cleanup watchers
+		this.watcher?.unwatch(actor.currentRoute);
+		this.watcher = null;
+	}
+}
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L376)
+
+Connect the router bridge to the Actor
+
+Called when Infrastructure should begin observing Actor signals and
+synchronizing its state (e.g., browser URL) with Actor state.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when connection is established, or void for synchronous connection
+
+#### Example
+
+```typescript
+const bridge: RouterBridge = createBridge(actor, router);
+await bridge.connect();
+// Bridge now observing actor.currentRoute signal
+```
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void | Promise<void>;
+```
+
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L392)
+
+Disconnect the router bridge from the Actor
+
+Called when Infrastructure should stop observing and clean up resources
+(e.g., signal watchers, event listeners).
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when disconnection is complete, or void for synchronous disconnection
+
+#### Example
+
+```typescript
+await bridge.disconnect();
+// Bridge stopped observing, resources cleaned up
+```

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

@@ -0,0 +1,9 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RoutableActor
+
+# Type Alias: RoutableActor
+
+```ts
+type RoutableActor = AbstractActor<AnyActorLogic> & Routable;
+```
+
+Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-sveltekit-router/src/types.ts#L10)

package/api/@xmachines/play-tanstack-react-router/README.md

@@ -1,194 +1,220 @@
-[Documentation](../../README.md) / @xmachines/play-tanstack-react-router
+[API](../../README.md) / @xmachines/play-tanstack-react-router
 
-# @xmachines/play-tanstack-react-router
+<!-- generated-by: gsd-doc-writer -->
 
-**TanStack React Router adapter for XMachines Play using the RouterBridge pattern.**
+# @xmachines/play-tanstack-react-router
 
-## Overview
+TanStack Router (React) adapter for XMachines Play — synchronizes browser URL with actor state through passive infrastructure.
 
-`@xmachines/play-tanstack-react-router` connects a Play actor to TanStack Router through `TanStackReactRouterBridge`.
+Part of the [xmachines-js monorepo](../../README.md).
 
-The bridge extends `RouterBridgeBase` from `@xmachines/play-router`, so adapter behavior stays consistent across frameworks:
+## Installation
 
-- Actor route signal (`actor.currentRoute`) drives router navigation.
-- Router history events send `play.route` intents back to the actor.
-- Guarded state transitions remain actor-owned (Actor Authority).
+```bash
+pnpm add @xmachines/play-tanstack-react-router
+```
 
-## Installation
+**Peer dependencies** (install separately):
 
 ```bash
-npm install @tanstack/react-router react
-npm install @xmachines/play-tanstack-react-router @xmachines/play-router @xmachines/play-react
+pnpm add @tanstack/react-router react react-dom xstate
 ```
 
-## Current Exports
+Requires:
 
-- `TanStackReactRouterBridge`
-- `RouteMap`, `createRouteMapFromTree`, `RouteMapping` (type)
-- `extractParams`, `extractQueryParams`
-- `PlayRouterProvider` + `PlayRouterProviderProps`
-- re-exports: `extractMachineRoutes`, `createRouteMap`, `RouterBridge`, `PlayRouteEvent`
+- `@tanstack/react-router` `^1.168.8`
+- `react` `^18.0.0` or `^19.0.0`
+- `react-dom` `^18.0.0` or `^19.0.0`
+- `xstate` `^6.0.0-alpha.19`
 
-Peer dependencies:
+## Usage
 
-- `@tanstack/react-router` `^1.166.7`
-- `react` `^18 || ^19`
-- `xstate` `^5.0.0`
+### `PlayRouterProvider` — React component (recommended)
 
-## URLPattern Support
+`PlayRouterProvider` is the primary integration point. It creates a `TanStackReactRouterBridge` on mount, keeps it connected for the component lifetime, and tears it down on unmount.
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via `@xmachines/play-router`.
+```tsx
+import { useMemo, useEffect } from "react";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
+import {
+	PlayRouterProvider,
+	createRouteMapFromTree,
+	extractMachineRoutes,
+} from "@xmachines/play-tanstack-react-router";
+import { definePlayer } from "@xmachines/play-xstate";
 
-URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router` installation](../play-router/README.md) for details.
+function createAppRuntime() {
+	const actor = definePlayer({ machine, catalog })();
+	actor.start();
 
-## Quick Start
+	const routeTree = extractMachineRoutes(machine);
+	const routeMap = createRouteMapFromTree(routeTree);
+	const rootRoute = createRootRoute();
+	const router = createRouter({ routeTree: rootRoute });
 
-```tsx
+	return { actor, routeMap, router };
+}
+
+export function App() {
+	// All three props must be stable references — memoize to avoid reconnecting on every render
+	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} />
+			)}
+		/>
+	);
+}
+```
+
+> **Stable references:** `actor`, `router`, and `routeMap` must be stable across renders. If any prop changes identity, the bridge disconnects and reconnects. Use `useMemo` to create them once.
+
+### `TanStackReactRouterBridge` — headless class
+
+Use the bridge directly when you don't need the React wrapper, or when integrating with a custom lifecycle:
+
+```typescript
 import { createRouter } from "@tanstack/react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
 import {
 	TanStackReactRouterBridge,
 	createRouteMapFromTree,
+	extractMachineRoutes,
 } from "@xmachines/play-tanstack-react-router";
 
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
-
-const router = createRouter({ routeTree: tanstackRouteTree });
-
+const router = createRouter({ routeTree });
 const actor = definePlayer({ machine, catalog })();
-actor.start();
+const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
 
 const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
 
-// later
+// Cleanup when done
 bridge.disconnect();
 ```
 
-### React convenience wrapper
+## API Summary
 
-Use `PlayRouterProvider` when you want bridge lifecycle wiring in a component:
+### `TanStackReactRouterBridge`
 
-```tsx
-import { PlayRenderer } from "@xmachines/play-react";
-
-<PlayRouterProvider
-	actor={actor}
-	router={router}
-	routeMap={routeMap}
-	renderer={(currentActor, currentRouter) => (
-		<PlayRenderer actor={currentActor} components={components} />
-	)}
-/>;
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements bidirectional sync between actor state signals and TanStack Router history.
+
+```typescript
+class TanStackReactRouterBridge extends RouterBridgeBase {
+	constructor(router: TanStackRouterLike, actor: RoutableActor, routeMap: RouteMap);
+
+	connect(): void; // Start sync; subscribe to router.history and actor signals
+	disconnect(): void; // Stop sync; unsubscribe all listeners
+}
 ```
 
-## API
+Subscribes to `router.history` (not `router.subscribe("onBeforeLoad")`) so that back/forward browser navigation (popstate events) are captured even without a `<RouterProvider>` mounted.
 
-### `TanStackReactRouterBridge`
+### `PlayRouterProvider`
 
-Primary adapter class.
+React component that wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
 
-```ts
-class TanStackReactRouterBridge implements RouterBridge {
-	constructor(
-		router: TanStackRouterLike,
-		actor: AbstractActor<AnyActorLogic> & Routable,
-		routeMap: RouteMap,
-	);
-	connect(): void;
-	disconnect(): void;
+```typescript
+interface PlayRouterProviderProps<TActor> {
+	actor: TActor; // Must be stable
+	router: TanStackRouterInstance; // Must be stable
+	routeMap: RouteMap; // Must be stable
+	renderer: (actor: TActor, router: TanStackRouterInstance) => ReactNode;
 }
 ```
 
-### `RouteMap` and `createRouteMapFromTree`
-
-Map state IDs to URL paths and resolve URLs back to state IDs.
-
-`RouteMap` extends `BaseRouteMap` from `@xmachines/play-router`, inheriting bucket-indexed
-bidirectional route matching. No routing logic lives in the adapter itself.
+### `TanStackRouterLike`
+
+Structural type for the router instance — accepts any object with the required `navigate` and `history` shape, making it testable without creating a full TanStack Router:
+
+```typescript
+type TanStackRouterLike = {
+	navigate(args: { to: string }): void;
+	load?(): void | Promise<void>;
+	history: {
+		location: { pathname: string; search?: string };
+		subscribe(
+			handler: (event: { location: { pathname: string; search?: string } }) => void,
+		): () => void;
+	};
+};
+```
 
-```ts
-// RouteMap is a thin subclass of BaseRouteMap — no extra methods
-class RouteMap extends BaseRouteMap {}
+### `RouteNavigateEvent`
 
-// Inherited API:
-routeMap.getStateIdByPath(path: string): string | null
-routeMap.getPathByStateId(stateId: string): string | null
+Event sent to the actor when the browser navigates:
 
-// Factory from a machine route tree:
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap
+```typescript
+interface RouteNavigateEvent {
+	readonly type: "route.navigate";
+	readonly path: string; // e.g. "/dashboard" or "/posts/123"
+}
 ```
 
-`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+### Re-exported from `@xmachines/play-router`
 
-```ts
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
+```typescript
+// Route map construction
+RouteMap
+createRouteMap(mappings: RouteMapping[]): RouteMap
+createRouteMapFromTree(routeTree): RouteMap
+extractMachineRoutes(machine): RouteTree
 
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-routeMap.getStateIdByPath("/unknown"); // null
+// Types
+type RouteMapOptions
+type RouteMapping
+type RouterBridge
+type PlayRouteEvent
 ```
 
-### `PlayRouterProvider`
+## How It Works
 
-React wrapper around `TanStackReactRouterBridge`.
-
-```ts
-interface PlayRouterProviderProps {
-	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
-	router: TanStackRouterLike;
-	routeMap: RouteMap;
-	renderer: (
-		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
-		router: TanStackRouterLike,
-	) => ReactNode;
-}
-```
+The bridge implements the **Passive Infrastructure** invariant from the XMachines RFC:
 
-### Utilities and re-exports
+1. **Actor → Router:** When `actor.currentRoute` signal changes, the bridge calls `router.navigate({ to: path })`. The URL updates to reflect the new actor state.
+2. **Router → Actor:** When `router.history.subscribe` fires (link clicks, `back`/`forward` buttons, `history.pushState`), the bridge sends a `play.route` event to the actor. The actor's guards decide whether navigation is valid — the router never enforces business logic.
+3. **Circular update prevention:** A `lastSyncedPath` guard suppresses round-trip updates so an actor → router navigation does not trigger a redundant router → actor send.
+4. **Deep-link and restore:** On `connect()`, the bridge reads `router.history.location.pathname` (which reflects `window.location` immediately, before `router.load()` runs) and determines whether to sync the actor from the URL (deep-link) or push the actor's restored route to the URL (snapshot restore).
 
-- `extractParams`, `extractQueryParams`
-- `extractMachineRoutes`, `createRouteMap` (re-exported from `@xmachines/play-router`)
-- `RouterBridge`, `PlayRouteEvent` types
+## Testing
 
-## Examples
+Run tests for this package in isolation:
 
-- Multi-router integration guide: `docs/examples/multi-router-integration.md`
-- Routing patterns guide: `docs/examples/routing-patterns.md`
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router test
+```
 
-## Architecture
+From the monorepo root:
 
-Bridge-first flow:
+```bash
+pnpm test
+```
 
-1. `RouterBridgeBase.connect()` performs initial actor/router synchronization.
-2. Actor route updates call TanStack navigation (`router.navigate({ to })`).
-3. TanStack history updates are subscribed and translated to `play.route` events.
-4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
+Tests cover RouterBridge protocol compliance, actor ↔ router bidirectional sync, circular update prevention, deep-link and snapshot-restore scenarios, and `PlayRouterProvider` lifecycle (mount/unmount/reconnect).
 
-This keeps routing infrastructure passive while preserving business-logic control.
+## Demo
 
-## Historical Note
+A runnable React + TanStack Router integration demo is available under `examples/demo/`. To run it from the repository root:
 
-`SignalSyncedHistory` and `createPlayRouter` are legacy migration-era APIs and are not part of the current quick-start path. Use `TanStackReactRouterBridge` + `RouteMap` for new integrations.
+```bash
+pnpm install
+pnpm --filter @xmachines/play-tanstack-react-router-demo run dev
+```
 
-## Related Packages
+Then open `http://localhost:3000`.
 
-- [@xmachines/play-router](../play-router/README.md)
-- [@xmachines/play-xstate](../play-xstate/README.md)
-- [@xmachines/play-react](../play-react/README.md)
+The demo shows actor-authoritative routing with a shared auth machine: TanStack Router updates the URL, `PlayRouterProvider` translates it to a `play.route` event, and the actor's guards decide whether access is permitted.
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](./LICENSE).
 
 @xmachines/play-tanstack-react-router
 
@@ -202,25 +228,28 @@ Synchronizes browser URL with actor state through passive infrastructure.
 
 ## Interfaces
 
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouteNavigateEvent](interfaces/RouteNavigateEvent.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases
 
+- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
 
 ## Variables
 
-- [extractMachineRoutes](variables/extractMachineRoutes.md)
+- [PlayRouterProvider](variables/PlayRouterProvider.md)
 
 ## Functions
 
+- [createPlayRouterProvider](functions/createPlayRouterProvider.md)
 - [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
-- [extractParams](functions/extractParams.md)
-- [extractQueryParams](functions/extractQueryParams.md)
-- [PlayRouterProvider](functions/PlayRouterProvider.md)
+- [extractMachineRoutes](functions/extractMachineRoutes.md)