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

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/classes/RouteMap.md

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L100)
+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.
 
@@ -50,7 +50,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): BaseRouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L125)
+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.
 
@@ -78,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L209)
+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.
 
@@ -109,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L174)
+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.
 

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

@@ -2,7 +2,7 @@
 
 # Class: SolidRouterBridge
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L48)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L48)
 
 TanStack Solid Router integration bridge extending RouterBridgeBase
 
@@ -25,7 +25,7 @@ new SolidRouterBridge(
    routeMap): SolidRouterBridge;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L58)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L58)
 
 Create a TanStack Solid Router bridge.
 
@@ -49,15 +49,15 @@ Create a TanStack Solid Router bridge.
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L99)   |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L87)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L86)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L89)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L88)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L100) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L102) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L101) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L90)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L89)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L102) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L101) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L90)   |
 
 ## Methods
 
@@ -67,7 +67,7 @@ Create a TanStack Solid Router bridge.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L126)
+Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L126)
 
 Connect the router bridge to the Actor.
 
@@ -99,7 +99,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L209)
+Defined in: [play-router/src/router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L209)
 
 Disconnect the router bridge from the Actor.
 
@@ -121,7 +121,7 @@ Stops signal watching and unregisters framework-specific router listener.
 dispose(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L130)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L130)
 
 Dispose the bridge (alias for disconnect).
 
@@ -137,7 +137,7 @@ Dispose the bridge (alias for disconnect).
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L318)
+Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L318)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -175,7 +175,7 @@ When URLPattern is absent and the route is parameterized
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L355)
+Defined in: [play-router/src/router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L355)
 
 Extract query parameters from URL search string.
 
@@ -203,7 +203,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L83)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L83)
 
 Get the current pathname at connect() time for deep-link / restore detection.
 
@@ -227,7 +227,7 @@ used by `TanStackReactRouterBridge`.
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L92)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L92)
 
 Return the initial URL search string for query-param forwarding on `connect()`.
 
@@ -249,7 +249,7 @@ Reads `router.history.location.search` — same source as `getInitialRouterPath(
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L72)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L72)
 
 Navigate TanStack Solid Router to the given path.
 
@@ -275,7 +275,7 @@ Navigate TanStack Solid Router to the given path.
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L340)
+Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L340)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -314,7 +314,7 @@ Concrete URL path, or `null` if navigation should be skipped
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L260)
+Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L260)
 
 Sync actor state when router location changes.
 
@@ -344,7 +344,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L240)
+Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L240)
 
 Sync router location when actor route signal changes.
 
@@ -377,7 +377,7 @@ suppressed as circular echoes.
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L122)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L122)
 
 Stop watching TanStack Router changes.
 
@@ -397,7 +397,7 @@ Stop watching TanStack Router changes.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L111)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L111)
 
 Subscribe to ALL navigation events via router.history.
 

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

@@ -6,7 +6,7 @@
 function PlayRouterProvider<TActor>(props): any;
 ```
 
-Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L19)
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L19)
 
 ## Type Parameters
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/create-route-map-from-machine.ts#L26)
+Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map-from-machine.ts#L26)
 
 Create a `BaseRouteMap` from an XState state machine.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L223)
+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
 
@@ -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:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/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.26/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.26/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.26/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.26/packages/play-router/src/types.ts#L224) |
+| <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-solid-router/interfaces/PlayRouterProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L11)
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L11)
 
 ## Type Parameters
 
@@ -14,7 +14,7 @@ Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:11](https:/
 
 | Property                                  | Type                                                          | Description                                                                 | Defined in                                                                                                                                                                                          |
 | ----------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                                                      | -                                                                           | [play-tanstack-solid-router/src/play-router-provider.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L12) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                                  | Renderer callback receives the same concrete actor type that was passed in. | [play-tanstack-solid-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L16) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                          | -                                                                           | [play-tanstack-solid-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L14) |
-| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | -                                                                           | [play-tanstack-solid-router/src/play-router-provider.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L13) |
+| <a id="property-actor"></a> `actor`       | `TActor`                                                      | -                                                                           | [play-tanstack-solid-router/src/play-router-provider.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L12) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                                  | Renderer callback receives the same concrete actor type that was passed in. | [play-tanstack-solid-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L16) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                          | -                                                                           | [play-tanstack-solid-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L14) |
+| <a id="property-router"></a> `router`     | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | -                                                                           | [play-tanstack-solid-router/src/play-router-provider.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L13) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L57)
+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)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/setting
 
 | 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.26/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.26/packages/play-router/src/base-route-map.ts#L59) |
+| <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-solid-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L271)
+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:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L287)
+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:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L303)
+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-solid-router/type-aliases/RoutableActor.md

@@ -6,6 +6,6 @@
 type RoutableActor = AbstractActor<AnyActorLogic> & Routable & Viewable;
 ```
 
-Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L8)
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L8)
 
 Minimum actor shape accepted by PlayRouterProvider.

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

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

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

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L27)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L27)
 
 ## Properties
 
@@ -16,7 +16,7 @@ Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:27](https://g
 history: object;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L29)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L29)
 
 #### location
 
@@ -63,7 +63,7 @@ subscribe(handler): () => void;
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L28)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L28)
 
 #### Parameters
 

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

@@ -2,7 +2,7 @@
 
 # TanStack Solid Router Demo
 
-Solid + `@tanstack/solid-router` demonstration of the Play architecture with TanStack router integration.
+Solid + `@tanstack/solid-router` integration demo for the XMachines Play architecture with actor-authoritative routing.
 
 ## What This Demonstrates
 
@@ -14,14 +14,14 @@ Solid + `@tanstack/solid-router` demonstration of the Play architecture with Tan
 
 ## Running the Demo
 
-From this directory (`packages/play-tanstack-solid-router/examples/demo`):
+From the repository root:
 
 ```bash
 npm install
-npm run dev
+npm run dev -w packages/play-tanstack-solid-router/examples/demo
 ```
 
-Open `http://localhost:5173`.
+Then open `http://localhost:3005`.
 
 ## Step-by-Step Code Flow
 
@@ -63,12 +63,12 @@ return (
 
 ## Key Files
 
-- `src/App.tsx` - Wires actor lifecycle, route map, TanStack router setup, and provider/renderer integration.
-- `src/main.tsx` - Vite bootstrap for the Solid TanStack demo.
-- `src/components/` - Demo views that dispatch machine events.
-- `test/library-pattern.test.ts` - Invariant and architecture checks for package behavior.
-- `test/browser/startup.browser.test.ts` - Browser startup and wiring checks.
-- `test/browser/auth-flow.browser.test.ts` - Browser auth + route-flow checks.
+- `src/App.tsx` - actor lifecycle, route map, TanStack router setup, and provider/renderer integration
+- `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/components/` - demo view components that dispatch machine events
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
+- `test/browser/xstate-route-events.browser.test.ts` - actor route event behavior in the browser
 
 ## State Machine & Architecture Details
 
@@ -76,7 +76,7 @@ The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** When a user clicks a link, TanStack Router updates the location object. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards and applies 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 Solid's `createEffect` and TanStack's `router.subscribe` to effortlessly observe location changes and signal updates.
+3. **Signal-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.subscribe` to observe location changes and signal updates without polling.
 
 ## Watcher Lifecycle and Cleanup Contract
 
@@ -96,31 +96,30 @@ The TanStack Solid adapter wraps TanStack's `router.navigate({ to })` and `route
 
 ## Available Scripts
 
-```bash
-npm run dev           # Start Vite dev server (default: http://localhost:5173)
-npm run build         # Build production assets
-npm run preview       # Preview production build locally
-npm run test          # Run unit/integration tests via Vitest
-npm run test:browser  # Run browser-mode tests via vitest.browser.config.ts
-```
+These commands are defined in `package.json`:
+
+| Command                                                                     | Description                      |
+| --------------------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w packages/play-tanstack-solid-router/examples/demo`          | Start Vite dev server            |
+| `npm run build -w packages/play-tanstack-solid-router/examples/demo`        | Build production bundle          |
+| `npm run preview -w packages/play-tanstack-solid-router/examples/demo`      | Preview built bundle             |
+| `npm run test -w packages/play-tanstack-solid-router/examples/demo`         | Run Vitest test suite            |
+| `npm run test:browser -w packages/play-tanstack-solid-router/examples/demo` | Run browser-focused Vitest suite |
 
 ## Verification
 
-Use these checks from this directory:
+Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run test
-npm run test:browser
+npm run test -w packages/play-tanstack-solid-router/examples/demo
+npm run test:browser -w packages/play-tanstack-solid-router/examples/demo
 ```
 
-Manual sanity check:
-
-1. Start with `npm run dev`.
-2. Open `http://localhost:5173`.
-3. Verify login/logout transitions and URL updates remain actor-driven, including protected route redirection.
+Expected result: library-pattern invariant tests and the browser shared-demo suite both pass, confirming actor-driven route and view updates including protected route redirection.
 
 ## Learn More
 
 - [TanStack Solid Router package README](../play-tanstack-solid-router/README.md)
+- [SolidJS package README](../play-solid/README.md)
 - [Solid Router demo README](../play-solid-router-demo/README.md)
 - [TanStack React Router demo README](../play-tanstack-react-router-demo/README.md)