@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,17 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteMapping
+
+# Interface: RouteMapping
+
+Defined in: [play-tanstack-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L22)
+
+Mapping between state machine state ID and router path.
+
+Structurally compatible with `BaseRouteMapping` from `@xmachines/play-router`.
+Fields are `readonly` — entries are immutable once passed to `RouteMap`.
+
+## Properties
+
+| Property                                | Modifier   | Type     | Description                                                          | Defined in                                                                                                                                                                                            |
+| --------------------------------------- | ---------- | -------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | Router path with optional parameters (e.g., `"/settings/:section?"`) | [play-tanstack-react-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L26) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State ID from state machine (e.g., `"home"`, `"settings.profile"`)   | [play-tanstack-react-router/src/route-map.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/route-map.ts#L24) |

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

@@ -0,0 +1,26 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouteNavigateEvent
+
+# Interface: RouteNavigateEvent
+
+Defined in: [play-tanstack-react-router/src/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/types.ts#L21)
+
+Event sent to actor when browser navigates.
+
+Browser navigation (user clicks link, back/forward button, direct URL entry)
+sends this event to the actor. The actor's guards determine if navigation
+is allowed based on business logic.
+
+Invariant: Passive Infrastructure - Router suggests, actor decides validity.
+
+## Example
+
+```typescript
+actor.send({ type: "route.navigate", path: "/dashboard" });
+```
+
+## Properties
+
+| Property                          | Modifier   | Type               | Description                                                  | Defined in                                                                                                                                                                                    |
+| --------------------------------- | ---------- | ------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path` | `readonly` | `string`           | Target route path (may include parameters, e.g., /posts/123) | [play-tanstack-react-router/src/types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/types.ts#L25) |
+| <a id="property-type"></a> `type` | `readonly` | `"route.navigate"` | Event type discriminant (extends XState event pattern)       | [play-tanstack-react-router/src/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/types.ts#L23) |

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

@@ -0,0 +1,104 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: play-router/dist/types.d.ts:229
+
+RouterBridge interface for runtime infrastructure adapters
+
+Defines the lifecycle connection between Infrastructure (e.g., TanStack 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
+
+TanStack Router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class TanStackRouterBridge 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
+
+[RFC Play v1 - Invariant INV-04](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: play-router/dist/types.d.ts:245
+
+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/dist/types.d.ts:260
+
+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-tanstack-react-router/type-aliases/TanStackRouterInstance.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackRouterInstance
+
+# Type Alias: TanStackRouterInstance
+
+```ts
+type TanStackRouterInstance = ConstructorParameters<typeof TanStackReactRouterBridge>[0];
+```
+
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/play-router-provider.tsx#L26)

package/api/@xmachines/play-tanstack-react-router/type-aliases/TanStackRouterLike.md

@@ -0,0 +1,78 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / TanStackRouterLike
+
+# Type Alias: TanStackRouterLike
+
+```ts
+type TanStackRouterLike = object;
+```
+
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L42)
+
+## Properties
+
+### history
+
+```ts
+history: object;
+```
+
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L45)
+
+#### subscribe()
+
+```ts
+subscribe(handler): () => void;
+```
+
+##### Parameters
+
+| Parameter | Type                |
+| --------- | ------------------- |
+| `handler` | (`event`) => `void` |
+
+##### Returns
+
+() => `void`
+
+---
+
+### state?
+
+```ts
+optional state?: object;
+```
+
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L44)
+
+#### location?
+
+```ts
+optional location?: object;
+```
+
+##### location.pathname?
+
+```ts
+optional pathname?: string;
+```
+
+## Methods
+
+### navigate()
+
+```ts
+navigate(args): void;
+```
+
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L43)
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `args`    | \{ `to`: `string`; \} |
+| `args.to` | `string`              |
+
+#### Returns
+
+`void`

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

@@ -0,0 +1,64 @@
+[Documentation](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / extractMachineRoutes
+
+# Variable: extractMachineRoutes
+
+```ts
+const extractMachineRoutes: (machine) => RouteTree;
+```
+
+Defined in: play-router/dist/extract-routes.d.ts:40
+
+Extract complete route tree from state machine graph
+
+Crawls machine starting from root, visits all state nodes (including nested
+and parallel), extracts meta.route metadata, validates route references,
+and builds hierarchical tree.
+
+## Parameters
+
+| Parameter | Type              | Description             |
+| --------- | ----------------- | ----------------------- |
+| `machine` | `AnyStateMachine` | XState v5 state machine |
+
+## Returns
+
+[`RouteTree`](../../play-router/interfaces/RouteTree.md)
+
+Route tree with root, byStateId map, and byPath map
+
+## Throws
+
+If route references non-existent state
+
+## Throws
+
+If route path is malformed (doesn't start with /)
+
+## Throws
+
+If parallel states define conflicting routes
+
+## Example
+
+```typescript
+import { createMachine } from "xstate";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+const machine = createMachine({
+	initial: "home",
+	states: {
+		home: { id: "home", meta: { route: "/" } },
+		dashboard: {
+			id: "dashboard",
+			meta: { route: "/dashboard" },
+			initial: "overview",
+			states: {
+				overview: { id: "overview", meta: { route: "/overview" } },
+			},
+		},
+	},
+});
+
+const tree = extractMachineRoutes(machine);
+console.log(tree.byPath.get("/dashboard/overview"));
+```

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

@@ -0,0 +1,126 @@
+[Documentation](../../README.md) / @xmachines/play-tanstack-react-router-demo
+
+# TanStack React Router Demo
+
+React + TanStack Router demonstration of Play's actor-authoritative routing and rendering model.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with TanStack Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From this directory (`packages/play-tanstack-react-router/examples/demo`):
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+## Step-by-Step Code Flow
+
+This demo uses provider-based integration centered on `PlayRouterProvider` and a route map generated from the machine:
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` creates/starts the actor from shared machine + catalog.
+3. `src/App.tsx` builds `routeMap` from `extractMachineRoutes(authMachine)` + `createRouteMapFromTree(routeTree)`.
+4. `PlayRouterProvider` bridges TanStack Router to the actor and renders `Shell` via `renderer(actor, router)`.
+5. `Shell` renders `PlayRenderer`, header/nav, and debug panel from actor state.
+6. Tests in `test/` and `test/browser*/` validate invariant and runtime behavior.
+
+```tsx
+// src/App.tsx (shape)
+const routeTree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+return (
+	<PlayRouterProvider
+		actor={actor}
+		router={router}
+		routeMap={routeMap}
+		renderer={(currentActor, currentRouter) => (
+			<Shell actor={currentActor} router={currentRouter} />
+		)}
+	/>
+);
+```
+
+```tsx
+// src/components/Login.tsx (shape)
+<button onClick={() => actor.send({ type: "auth.login", username })}>Login</button>
+```
+
+Shared business logic comes from the common demo machine/catalog module (`authMachine` and `catalog`), so routing decisions remain machine-driven and framework-independent.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/App.tsx` - actor lifecycle, route-map creation, provider wiring, and `Shell` rendering
+- `src/components/` - UI components that send actor events and render state-driven views
+- `test/actor-authority.test.ts` - actor authority and guarded navigation behavior
+- `test/strict-separation.test.ts` - machine/view infrastructure separation contracts
+- `test/browser-e2e/auth-flow.browser.test.tsx` - canonical browser auth flow
+- `test/browser/` - extended browser checks for URL sync, history behavior, and route event flow
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user navigates to a protected route, TanStack Router updates the URL. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and executes state transitions.
+2. **Passive Infrastructure:** The router does not execute route loaders or guards for business logic. The actor dictates whether navigation is permitted.
+3. **Signal-Only Reactivity:** The bridge leverages React's internal mechanisms combined with TanStack's `router.subscribe` to react precisely when signals update, without relying on `useEffect` synchronization inside the application codebase.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and trigger React state updates
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit and lifecycle-bound: the provider automatically triggers `bridge.disconnect()` when the component tree unmounts to prevent memory leaks and zombie subscriptions.
+
+## Adapter Boundaries
+
+The TanStack React adapter wraps TanStack's `router.navigate({ to })` and `router.subscribe` methods while delegating core synchronization policy to `RouterBridgeBase`.
+
+## Available Scripts
+
+```bash
+npm run dev            # Start Vite dev server (http://localhost:3000)
+npm run build          # Build production assets
+npm run preview        # Preview production build locally
+npm run test           # Run Vitest suite
+npm run test:vitest    # Explicit Vitest command alias
+npm run test:browser   # Browser-focused test run
+npm run test:browser:e2e # E2E-specific browser suite
+npm run test:e2e       # Alias to test:browser
+```
+
+## Verification
+
+Run the core invariant checks referenced by this demo docs:
+
+```bash
+npm run test:vitest -- test/actor-authority.test.ts test/strict-separation.test.ts
+npm run test:browser
+```
+
+Manual sanity flow:
+
+1. Run `npm run dev` and open `http://localhost:3000`.
+2. Attempt protected navigation while logged out and confirm guard-driven behavior.
+3. Log in, then confirm route and view updates stay in sync.
+
+## Learn More
+
+- [TanStack React Router package README](../play-tanstack-react-router/README.md)
+- [Solid Router demo README](../play-solid-router-demo/README.md)
+- [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)