@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-react-router/classes/RouteMap.md

@@ -0,0 +1,137 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [play-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/route-map.ts#L54)
+
+Bidirectional route mapper for React Router.
+
+Extends [BaseRouteMap](../../play-router/classes/BaseRouteMap.md) — all matching logic lives there.
+This class exists to provide a React Router-specific type name and to allow
+future adapter-specific extensions without breaking the shared base.
+
+**Inherited API:**
+
+- `getStateIdByPath(path): string | null` — path → state ID
+- `getPathByStateId(stateId): string | null` — state ID → path pattern
+
+## Example
+
+```typescript
+const routeMap = new RouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+routeMap.getStateIdByPath("/profile/123"); // "profile"
+routeMap.getPathByStateId("home"); // "/"
+```
+
+## Extends
+
+- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new RouteMap(mappings): RouteMap;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:81
+
+Build a route map from an array of state ID ↔ path mappings.
+
+Static paths (no `:param`) are indexed in an O(1) `Map`.
+Parameterized paths are compiled to `RegExp` and grouped into first-segment
+buckets for efficient candidate selection.
+
+#### Parameters
+
+| Parameter  | Type                                                                     | Description                                                                                                       |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+
+#### Returns
+
+`RouteMap`
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:111
+
+Look up the path pattern registered for a state ID.
+
+#### Parameters
+
+| Parameter | Type     | Description                                               |
+| --------- | -------- | --------------------------------------------------------- |
+| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The registered path pattern, or `null` if the state ID is unknown
+
+#### Example
+
+```typescript
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:98
+
+Resolve a URL path to its mapped state ID.
+
+Strips query strings and hash fragments before matching. Tries an O(1) exact
+lookup first, then falls back to bucket-indexed pattern matching. Results are
+cached after the first pattern match.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------ |
+| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The mapped state ID, or `null` if no route matches
+
+#### Example
+
+```typescript
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/unknown"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)

package/api/@xmachines/play-react-router/functions/PlayRouterProvider.md

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProvider
+
+# Function: PlayRouterProvider()
+
+```ts
+function PlayRouterProvider(__namedParameters): Element;
+```
+
+Defined in: [play-react-router/src/play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L20)
+
+## Parameters
+
+| Parameter           | Type                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `__namedParameters` | [`PlayRouterProviderProps`](../interfaces/PlayRouterProviderProps.md) |
+
+## Returns
+
+`Element`

package/api/@xmachines/play-react-router/functions/createRouteMapFromTree.md

@@ -0,0 +1,35 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / createRouteMapFromTree
+
+# Function: createRouteMapFromTree()
+
+```ts
+function createRouteMapFromTree(routeTree): RouteMap;
+```
+
+Defined in: [play-react-router/src/route-map.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/route-map.ts#L73)
+
+Create RouteMap from RouteTree
+
+Converts XMachines route tree to RouteMap for use with router adapters.
+
+## Parameters
+
+| Parameter   | Type                                                     | Description                            |
+| ----------- | -------------------------------------------------------- | -------------------------------------- |
+| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | Route tree from extractMachineRoutes() |
+
+## Returns
+
+[`RouteMap`](../classes/RouteMap.md)
+
+RouteMap instance
+
+## Example
+
+```typescript
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { createRouteMapFromTree } from "@xmachines/play-react-router";
+
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+```

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

@@ -0,0 +1,119 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: play-router/dist/types.d.ts:182
+
+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
+
+Event discriminator (always "play.route")
+
+## Param
+
+Target state ID with # prefix (e.g., '#home', '#profile')
+
+## Param
+
+Merged path + query parameters (path parameters win conflicts)
+
+## Param
+
+Query parameters only (isolated from path params)
+
+## Param
+
+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" }, // Merged: path + query
+	query: { tab: "security" }, // Query-only
+};
+actor.send(event);
+// Resolves to route: /settings/profile?tab=security
+```
+
+## See
+
+[RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.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/dist/types.d.ts:187 |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:185 |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:186 |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | play-router/dist/types.d.ts:184 |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | play-router/dist/types.d.ts:183 |

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

@@ -0,0 +1,14 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProviderProps
+
+# Interface: PlayRouterProviderProps
+
+Defined in: [play-react-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L10)
+
+## Properties
+
+| Property                                  | Type                                                                                                                                                                                            | Defined in                                                                                                                                                                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) & [`Viewable`](../../play-actor/interfaces/Viewable.md) | [play-react-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L11) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`                                                                                                                                                              | [play-react-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L14) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                            | [play-react-router/src/play-router-provider.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L13) |
+| <a id="property-router"></a> `router`     | `Router$1`                                                                                                                                                                                      | [play-react-router/src/play-router-provider.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/play-router-provider.tsx#L12) |

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

@@ -0,0 +1,17 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / RouteMapping
+
+# Interface: RouteMapping
+
+Defined in: [play-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-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-react-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-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-react-router/src/route-map.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-react-router/src/route-map.ts#L24) |

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

@@ -0,0 +1,104 @@
+[Documentation](../../../README.md) / [@xmachines/play-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-react-router-demo/README.md

@@ -0,0 +1,137 @@
+[Documentation](../../README.md) / @xmachines/play-react-router-demo
+
+# React Router Demo
+
+React Router v7 integration demo for the XMachines Play architecture.
+
+## What This Demonstrates
+
+- Shared auth machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with React Router
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Canonical TC39 Signals lifecycle mapped to React's rendering loop
+- Non-browser invariant tests plus browser E2E coverage
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w packages/play-react-router/examples/demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` creates/starts the actor from shared machine + catalog.
+3. Route metadata is extracted from the machine and converted into a route map.
+4. `PlayRouterProvider` wires `createBrowserRouter` and actor navigation in both directions.
+5. `Shell` (inside `App.tsx`) renders `PlayRenderer` and actor-driven navigation UI.
+6. Browser tests in `test/browser/` validate startup and auth navigation flow.
+
+```tsx
+// src/main.tsx (shape)
+createRoot(document.getElementById("root")!).render(
+	<StrictMode>
+		<App />
+	</StrictMode>,
+);
+```
+
+```tsx
+// src/App.tsx (shape)
+const createPlayer = definePlayer({ machine: authMachine, catalog });
+const actor = createPlayer();
+actor.start();
+
+const routeTree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+return (
+	<PlayRouterProvider
+		actor={actor}
+		router={router}
+		routeMap={routeMap}
+		renderer={(currentActor, currentRouter) => {
+			void currentActor;
+			return <RouterProvider router={currentRouter} />;
+		}}
+	/>
+);
+```
+
+```tsx
+// src/components/Login.tsx (shape)
+export function Login() {
+	return (
+		<button onClick={() => actor.send({ type: "auth.login", username, password })}>
+			Login
+		</button>
+	);
+}
+```
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/App.tsx` - actor lifecycle, route extraction, provider wiring, and renderer composition
+- `src/components/` - demo views bound to catalog component keys (Home, Login, Dashboard, Profile, etc.)
+- `test/browser/startup.browser.test.tsx` - startup assertion for public home + login control
+- `test/browser/auth-flow.browser.test.tsx` - end-to-end login -> dashboard -> profile -> logout flow
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** Navigation triggers URL changes, which the `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates whether navigation is permitted. The React application only triggers renders.
+3. **Signal-Only Reactivity:** The bridge leverages React's `useSyncExternalStore` (internally within the hooks) to react precisely when signals update, without polluting the React component tree with `useState` or `useEffect` for business logic.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the same watcher lifecycle used across `@xmachines/play-signals` and framework adapters:
+
+1. `notify`
+2. `queueMicrotask`
+3. Drain pending work with `getPending()`
+4. Read actor signals and project framework-local state
+5. Re-arm via `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: bridge/provider teardown must call `disconnect`/`unwatch` paths, never rely on GC-only cleanup. The `PlayRouterProvider` handles this natively on component unmount.
+
+## Adapter Boundaries
+
+`PlayRouterProvider` and the React Router bridge stay passive infrastructure. Business validity remains actor-owned, while `RouterBridgeBase` remains the shared policy layer and the concrete React adapter stays a thin port, delegating DOM synchronization to React Router.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                            | Description                      |
+| ------------------------------------------------------------------ | -------------------------------- |
+| `npm run dev -w packages/play-react-router/examples/demo`          | Start Vite dev server            |
+| `npm run build -w packages/play-react-router/examples/demo`        | Build production bundle          |
+| `npm run preview -w packages/play-react-router/examples/demo`      | Preview built bundle             |
+| `npm run test -w packages/play-react-router/examples/demo`         | Run Vitest test suite            |
+| `npm run test:browser -w packages/play-react-router/examples/demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+npm run test -w packages/play-react-router/examples/demo
+npm run test:browser -w packages/play-react-router/examples/demo
+```
+
+Expected result: tests pass for startup and auth-flow browser scenarios.
+
+## Learn More
+
+- [React Router package README](../play-react-router/README.md)
+- [React package README](../play-react/README.md)