@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L216)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -30,7 +30,7 @@ Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
@@ -85,7 +85,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Merged: path + query
+	params: { section: "profile" }, // Path-only route parameter
 	query: { tab: "security" }, // Query-only
 };
 actor.send(event);
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L221) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L219) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L220) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L218) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L217) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L224) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/play-router-provider.tsx#L30)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/play-router-provider.tsx#L30)
 
 ## Type Parameters
 
@@ -14,7 +14,7 @@ Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:30](https:/
 
 | Property                                  | Type                                                          | Description                                                                 | Defined in                                                                                                                                                                                          |
 | ----------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                                                      | -                                                                           | [play-tanstack-react-router/src/play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/play-router-provider.tsx#L34) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`                            | Renderer callback receives the same concrete actor type that was passed in. | [play-tanstack-react-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/play-router-provider.tsx#L38) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                          | -                                                                           | [play-tanstack-react-router/src/play-router-provider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/play-router-provider.tsx#L36) |
-| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | -                                                                           | [play-tanstack-react-router/src/play-router-provider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/play-router-provider.tsx#L35) |
+| <a id="property-actor"></a> `actor`       | `TActor`                                                      | -                                                                           | [play-tanstack-react-router/src/play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/play-router-provider.tsx#L34) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`                            | Renderer callback receives the same concrete actor type that was passed in. | [play-tanstack-react-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/play-router-provider.tsx#L38) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                          | -                                                                           | [play-tanstack-react-router/src/play-router-provider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/play-router-provider.tsx#L36) |
+| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | -                                                                           | [play-tanstack-react-router/src/play-router-provider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/play-router-provider.tsx#L35) |

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

@@ -2,16 +2,26 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-tanstack-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/route-map.ts#L22)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L57)
 
-Mapping between state machine state ID and router path.
+A single state ID ↔ path mapping entry.
 
-Structurally compatible with `BaseRouteMapping` from `@xmachines/play-router`.
-Fields are `readonly` — entries are immutable once passed to `RouteMap`.
+Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`BaseRouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
+const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## 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/v1.0.0-beta.25/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/v1.0.0-beta.25/packages/play-tanstack-react-router/src/route-map.ts#L24) |
+| 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:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteNavigateEvent
 
-Defined in: [play-tanstack-react-router/src/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/types.ts#L21)
+Defined in: [play-tanstack-react-router/src/types.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/types.ts#L21)
 
 Event sent to actor when browser navigates.
 
@@ -22,5 +22,5 @@ actor.send({ type: "route.navigate", path: "/dashboard" });
 
 | 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/v1.0.0-beta.25/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/v1.0.0-beta.25/packages/play-tanstack-react-router/src/types.ts#L23) |
+| <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/v1.0.0-beta.27/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/v1.0.0-beta.27/packages/play-tanstack-react-router/src/types.ts#L23) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L264)
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L280)
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L296)
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

@@ -6,4 +6,4 @@
 type TanStackRouterInstance = ConstructorParameters<typeof TanStackReactRouterBridge>[0];
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/play-router-provider.tsx#L28)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/play-router-provider.tsx#L28)

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

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L42)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L42)
 
 ## Properties
 
@@ -16,7 +16,7 @@ Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https:
 history: object;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L45)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L45)
 
 #### location
 
@@ -24,7 +24,9 @@ Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:45](https:
 location: object;
 ```
 
-Current location — always reflects window.location immediately.
+Current location — populated from `window.location` when `createRouter()` runs,
+before `router.load()`. Always available in the browser.
+`router.state.location` is only populated after `router.load()` and may be stale.
 
 ##### location.pathname
 
@@ -54,29 +56,21 @@ subscribe(handler): () => void;
 
 () => `void`
 
----
+## Methods
 
-### state?
+### load()?
 
 ```ts
-optional state?: object;
+optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L44)
-
-#### location?
-
-```ts
-optional location?: object;
-```
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L44)
 
-##### location.pathname?
+#### Returns
 
-```ts
-optional pathname?: string;
-```
+`void` \| `Promise`\<`void`\>
 
-## Methods
+---
 
 ### navigate()
 
@@ -84,7 +78,7 @@ optional pathname?: string;
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L43)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L43)
 
 #### Parameters
 

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

@@ -2,7 +2,7 @@
 
 # TanStack React Router Demo
 
-React + TanStack Router demonstration of Play's actor-authoritative routing and rendering model.
+React + TanStack Router integration demo for the XMachines Play architecture with actor-authoritative routing.
 
 ## What This Demonstrates
 
@@ -13,25 +13,25 @@ React + TanStack Router demonstration of Play's actor-authoritative routing and
 
 ## Running the Demo
 
-From this directory (`packages/play-tanstack-react-router/examples/demo`):
+From the repository root:
 
 ```bash
 npm install
-npm run dev
+npm run dev -w packages/play-tanstack-react-router/examples/demo
 ```
 
-Open `http://localhost:3000`.
+Then 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:
+Use this order to understand the implementation:
 
 1. `src/main.tsx` mounts `<App />`.
 2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor from shared machine + catalog and start it once per mounted app.
 3. `createAppRuntime()` memoizes `routeMap` from `extractMachineRoutes(authMachine)` + `createRouteMapFromTree(routeTree)`.
 4. `createAppRuntime()` also memoizes the TanStack router, then `PlayRouterProvider` bridges it 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.
+6. Tests in `test/` and `test/browser/` validate invariant and runtime behavior.
 
 ```tsx
 // src/App.tsx (shape)
@@ -65,8 +65,6 @@ return (
 <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 />`
@@ -74,8 +72,9 @@ Shared business logic comes from the common demo machine/catalog module (`authMa
 - `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
+- `test/browser/shared-demo.browser.test.tsx` - canonical browser auth flow
+- `test/browser/auth-flow.browser.test.tsx` - extended browser auth flow checks
+- `test/browser/back-forward-sync.browser.test.tsx` - URL sync and history behavior
 
 ## State Machine & Architecture Details
 
@@ -103,34 +102,29 @@ The TanStack React adapter wraps TanStack's `router.navigate({ to })` and `route
 
 ## 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
-```
+These commands are defined in `package.json`:
+
+| Command                                                                     | Description                      |
+| --------------------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w packages/play-tanstack-react-router/examples/demo`          | Start Vite dev server            |
+| `npm run build -w packages/play-tanstack-react-router/examples/demo`        | Build production bundle          |
+| `npm run preview -w packages/play-tanstack-react-router/examples/demo`      | Preview built bundle             |
+| `npm run test -w packages/play-tanstack-react-router/examples/demo`         | Run Vitest test suite            |
+| `npm run test:browser -w packages/play-tanstack-react-router/examples/demo` | Run browser-focused Vitest suite |
 
 ## Verification
 
-Run the core invariant checks referenced by this demo docs:
+Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test:vitest -- test/actor-authority.test.ts test/strict-separation.test.ts
-npm run test:browser
+npm run test -w packages/play-tanstack-react-router/examples/demo
+npm run test:browser -w packages/play-tanstack-react-router/examples/demo
 ```
 
-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.
+Expected result: invariant test suite and the browser shared-demo suite both pass, confirming actor authority, route sync, and guard-driven redirection.
 
 ## Learn More
 
 - [TanStack React Router package README](../play-tanstack-react-router/README.md)
-- [Solid Router demo README](../play-solid-router-demo/README.md)
+- [React package README](../play-react/README.md)
 - [TanStack Solid Router demo README](../play-tanstack-solid-router-demo/README.md)

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

@@ -108,7 +108,7 @@ class SolidRouterBridge {
 
 **Methods:**
 
-- `connect()` - Start bidirectional synchronization.
+- `connect()` - Start bidirectional synchronization. Both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
 - `disconnect()` - Stop synchronization and cleanup bridge resources.
 - `dispose()` - Alias of `disconnect()`.
 
@@ -116,7 +116,7 @@ class SolidRouterBridge {
 
 - Uses `RouterBridgeBase` TC39 watcher lifecycle for actor→router synchronization
 - Updates TanStack Router via `router.navigate({ to: path })` when actor state changes
-- Uses `router.subscribe` to watch history navigation events
+- Uses `router.history.subscribe` to watch history navigation events (covers PUSH, POP, BACK, FORWARD — works without `<RouterProvider>` mounted)
 - Sends `play.route` events to actor when user navigates
 
 ### `PlayTanStackRouterProvider`
@@ -219,12 +219,12 @@ The `RouterBridgeBase` architecture prevents infinite loops between router and a
 
 ## Comparison with @solidjs/router Adapter
 
-| Aspect            | @solidjs/router Adapter          | @tanstack/solid-router Adapter  |
-| ----------------- | -------------------------------- | ------------------------------- |
-| **Router API**    | `navigate(path)`                 | `router.navigate({ to })`       |
-| **Setup Context** | Must be _inside_ Router context  | Can wrap Router instance        |
-| **State Source**  | Uses Solid hooks (`useLocation`) | Subscribes to `router` directly |
-| **Reacting**      | `createEffect` on location       | `router.subscribe` callback     |
+| Aspect            | @solidjs/router Adapter          | @tanstack/solid-router Adapter      |
+| ----------------- | -------------------------------- | ----------------------------------- |
+| **Router API**    | `navigate(path)`                 | `router.navigate({ to })`           |
+| **Setup Context** | Must be _inside_ Router context  | Can wrap Router instance            |
+| **State Source**  | Uses Solid hooks (`useLocation`) | Subscribes to `router` directly     |
+| **Reacting**      | `createEffect` on location       | `router.history.subscribe` callback |
 
 ## Architecture
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-tanstack-solid-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-tanstack-solid-router/src/route-map.ts#L26)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -14,7 +14,8 @@ own and inherit the full public API from here.
 - Static paths (no `:param`) → O(1) `Map` lookup
 - Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
   of routes sharing the same first path segment
-- Results are cached after the first match
+- Results are cached after the first match in an LRU cache (default 500 entries,
+  configurable via the `cacheSize` constructor option)
 
 **Pattern syntax** (`:param` / `:param?`):
 
@@ -41,19 +42,15 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
-## Extends
-
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
-
 ## Constructors
 
 ### Constructor
 
 ```ts
-new RouteMap(mappings): RouteMap;
+new RouteMap(mappings, options?): BaseRouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L118)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -63,17 +60,15 @@ 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. |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
-`RouteMap`
-
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+`BaseRouteMap`
 
 ## Methods
 
@@ -83,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L202)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -106,10 +101,6 @@ 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()
@@ -118,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L167)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 
@@ -144,7 +135,3 @@ The mapped state ID, or `null` if no route matches
 map.getStateIdByPath("/profile/123"); // "profile"
 map.getStateIdByPath("/unknown"); // null
 ```
-
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)