@xmachines/play-tanstack-react-router 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -29,25 +29,15 @@ npm install @xmachines/play-tanstack-react-router @xmachines/play-router @xmachi
 
 Peer dependencies:
 
-- `@tanstack/react-router` `^1.0.0`
+- `@tanstack/react-router` `^1.166.7`
 - `react` `^18 || ^19`
+- `xstate` `^5.0.0`
 
-## Browser Support
+## URLPattern Support
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching.
+This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via `@xmachines/play-router`.
 
-Native support includes current Chrome, Firefox, and Safari 17.4+.
-For Node.js test environments or older browsers, install `urlpattern-polyfill`.
-
-```bash
-npm install urlpattern-polyfill
-```
-
-```ts
-if (!globalThis.URLPattern) {
-	await import("urlpattern-polyfill");
-}
-```
+URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router` installation](../play-router/README.md#installation) for details.
 
 ## Quick Start
 
@@ -112,16 +102,35 @@ class TanStackReactRouterBridge implements RouterBridge {
 
 ### `RouteMap` and `createRouteMapFromTree`
 
-Map state IDs to URL paths and resolve URLs back to state IDs:
+Map state IDs to URL paths and resolve URLs back to state IDs.
+
+`RouteMap` extends `BaseRouteMap` from `@xmachines/play-router`, inheriting bucket-indexed
+bidirectional route matching. No routing logic lives in the adapter itself.
 
 ```ts
-class RouteMap {
-	constructor(routes: Array<{ stateId: string; path: string }>);
-	getStateIdByPath(path: string): string | undefined;
-	getPathByStateId(stateId: string): string | undefined;
-}
+// RouteMap is a thin subclass of BaseRouteMap — no extra methods
+class RouteMap extends BaseRouteMap {}
+
+// Inherited API:
+routeMap.getStateIdByPath(path: string): string | null
+routeMap.getPathByStateId(stateId: string): string | null
 
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap;
+// Factory from a machine route tree:
+function createRouteMapFromTree(routeTree: RouteTree): RouteMap
+```
+
+`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+
+```ts
+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"); // "/"
+routeMap.getStateIdByPath("/unknown"); // null
 ```
 
 ### `PlayRouterProvider`
@@ -174,4 +183,7 @@ This keeps routing infrastructure passive while preserving business-logic contro
 
 ## License
 
-MIT
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.

package/dist/route-map.d.ts

@@ -10,75 +10,45 @@
  * @packageDocumentation
  */
 import type { RouteTree } from "@xmachines/play-router";
+import { BaseRouteMap } from "@xmachines/play-router";
 /**
- * Mapping between state machine state ID and router path
+ * 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`.
  */
 export interface RouteMapping {
-    /** State ID from state machine (e.g., "settings.profile") */
-    stateId: string;
-    /** Router path with optional parameters (e.g., "/settings/:section?") */
-    path: string;
+    /** State ID from state machine (e.g., `"home"`, `"settings.profile"`) */
+    readonly stateId: string;
+    /** Router path with optional parameters (e.g., `"/settings/:section?"`) */
+    readonly path: string;
 }
 /**
- * Bidirectional route mapper with pattern matching support
+ * Bidirectional route mapper for TanStack React Router.
+ *
+ * Extends {@link BaseRouteMap} — all matching logic lives there.
+ * This class exists to provide a TanStack React Router-specific type name and to
+ * allow future adapter-specific extensions without breaking the shared base.
  *
- * Maps between state IDs (XMachines actor) and paths (router).
- * Handles both exact matches (static paths) and pattern matches (parameterized paths).
+ * **Inherited API:**
+ * - `getStateIdByPath(path): string | null` — path → state ID
+ * - `getPathByStateId(stateId): string | null` — state ID → path pattern
+ *
+ * @extends BaseRouteMap
  *
  * @example
  * ```typescript
- * const routes: RouteMapping[] = [
- *   { stateId: "home", path: "/" },
- *   { stateId: "profile", path: "/profile/:userId" },
- *   { stateId: "settings", path: "/settings/:section?" }
- * ];
- *
- * const routeMap = new RouteMap(routes);
+ * 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");           // "/"
+ * routeMap.getPathByStateId("home");          // "/"
  * ```
  */
-export declare class RouteMap {
-    private stateIdToPath;
-    private pathToStateId;
-    private patterns;
-    /**
-     * Create RouteMap from route mappings
-     *
-     * @param routes - Array of state ID → path mappings
-     */
-    constructor(routes: RouteMapping[]);
-    /**
-     * Get state ID from router path
-     *
-     * Tries exact match first, then pattern match for parameterized paths.
-     *
-     * @param path - Router path (e.g., "/profile/123")
-     * @returns State ID or null if no match
-     *
-     * @example
-     * ```typescript
-     * routeMap.getStateIdByPath("/");             // "home" (exact match)
-     * routeMap.getStateIdByPath("/profile/123");  // "profile" (pattern match)
-     * ```
-     */
-    getStateIdByPath(path: string): string | null;
-    /**
-     * Get router path from state ID
-     *
-     * Returns the route pattern with parameter placeholders (not substituted).
-     *
-     * @param stateId - State machine state ID
-     * @returns Router path or null if no match
-     *
-     * @example
-     * ```typescript
-     * routeMap.getPathByStateId("home");     // "/"
-     * routeMap.getPathByStateId("profile");  // "/profile/:userId"
-     * ```
-     */
-    getPathByStateId(stateId: string): string | null;
+export declare class RouteMap extends BaseRouteMap {
 }
 /**
  * Create RouteMap from RouteTree

package/dist/route-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,wBAAwB,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ;IACpB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAA4D;IAE5E;;;;OAIG;gBACS,MAAM,EAAE,YAAY,EAAE;IA0BlC;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAa7C;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAcrE"}
+{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,QAAS,SAAQ,YAAY;CAAG;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAcrE"}

package/dist/route-map.js

@@ -9,102 +9,33 @@
  *
  * @packageDocumentation
  */
+import { BaseRouteMap } from "@xmachines/play-router";
 /**
- * Bidirectional route mapper with pattern matching support
+ * Bidirectional route mapper for TanStack React Router.
  *
- * Maps between state IDs (XMachines actor) and paths (router).
- * Handles both exact matches (static paths) and pattern matches (parameterized paths).
+ * Extends {@link BaseRouteMap} — all matching logic lives there.
+ * This class exists to provide a TanStack 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
+ *
+ * @extends BaseRouteMap
  *
  * @example
  * ```typescript
- * const routes: RouteMapping[] = [
- *   { stateId: "home", path: "/" },
- *   { stateId: "profile", path: "/profile/:userId" },
- *   { stateId: "settings", path: "/settings/:section?" }
- * ];
- *
- * const routeMap = new RouteMap(routes);
+ * 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");           // "/"
+ * routeMap.getPathByStateId("home");          // "/"
  * ```
  */
-export class RouteMap {
-    stateIdToPath;
-    pathToStateId;
-    patterns;
-    /**
-     * Create RouteMap from route mappings
-     *
-     * @param routes - Array of state ID → path mappings
-     */
-    constructor(routes) {
-        this.stateIdToPath = new Map();
-        this.pathToStateId = new Map();
-        this.patterns = [];
-        for (const { stateId, path } of routes) {
-            this.stateIdToPath.set(stateId, path);
-            // Check if path has parameters
-            if (path.includes(":")) {
-                // Convert :param and :param? to regex
-                const pattern = path
-                    .replace(/\/:[^/]+\?/g, "(?:/([^/]+))?") // Optional params with optional slash
-                    .replace(/:[^/]+/g, "([^/]+)"); // Required params
-                this.patterns.push({
-                    pattern: new RegExp(`^${pattern}$`),
-                    stateId,
-                    path,
-                });
-            }
-            else {
-                // Exact match for static paths
-                this.pathToStateId.set(path, stateId);
-            }
-        }
-    }
-    /**
-     * Get state ID from router path
-     *
-     * Tries exact match first, then pattern match for parameterized paths.
-     *
-     * @param path - Router path (e.g., "/profile/123")
-     * @returns State ID or null if no match
-     *
-     * @example
-     * ```typescript
-     * routeMap.getStateIdByPath("/");             // "home" (exact match)
-     * routeMap.getStateIdByPath("/profile/123");  // "profile" (pattern match)
-     * ```
-     */
-    getStateIdByPath(path) {
-        // Try exact match first
-        const exactMatch = this.pathToStateId.get(path);
-        if (exactMatch)
-            return exactMatch;
-        // Try pattern match
-        for (const { pattern, stateId } of this.patterns) {
-            if (pattern.test(path))
-                return stateId;
-        }
-        return null;
-    }
-    /**
-     * Get router path from state ID
-     *
-     * Returns the route pattern with parameter placeholders (not substituted).
-     *
-     * @param stateId - State machine state ID
-     * @returns Router path or null if no match
-     *
-     * @example
-     * ```typescript
-     * routeMap.getPathByStateId("home");     // "/"
-     * routeMap.getPathByStateId("profile");  // "/profile/:userId"
-     * ```
-     */
-    getPathByStateId(stateId) {
-        return this.stateIdToPath.get(stateId) || null;
-    }
+export class RouteMap extends BaseRouteMap {
 }
 /**
  * Create RouteMap from RouteTree

package/dist/route-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-map.js","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,QAAQ;IACZ,aAAa,CAAsB;IACnC,aAAa,CAAsB;IACnC,QAAQ,CAA4D;IAE5E;;;;OAIG;IACH,YAAY,MAAsB;QACjC,IAAI,CAAC,aAAa,GAAG,IAAI,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,IAAI,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QAEnB,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;YACxC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAEtC,+BAA+B;YAC/B,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,sCAAsC;gBACtC,MAAM,OAAO,GAAG,IAAI;qBAClB,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC,sCAAsC;qBAC9E,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,kBAAkB;gBACnD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;oBAClB,OAAO,EAAE,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC;oBACnC,OAAO;oBACP,IAAI;iBACJ,CAAC,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACP,+BAA+B;gBAC/B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACvC,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,IAAY;QAC5B,wBAAwB;QACxB,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,UAAU;YAAE,OAAO,UAAU,CAAC;QAElC,oBAAoB;QACpB,KAAK,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClD,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,OAAO,CAAC;QACxC,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,OAAe;QAC/B,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;IAChD,CAAC;CACD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB;IAC1D,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"route-map.js","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAetD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,QAAS,SAAQ,YAAY;CAAG;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB;IAC1D,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-tanstack-react-router",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.11",
   "description": "TanStack React Router adapter for XMachines Play - synchronizes browser URL with actor state through passive infrastructure",
   "keywords": [
     "routing",
@@ -12,6 +12,11 @@
   ],
   "license": "MIT",
   "author": "XMachines",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -20,32 +25,35 @@
     },
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo",
+    "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:browser": "vitest run",
+    "test": "vitest",
+    "test:browser": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@tanstack/react-router": "^1.166.7",
-    "@xmachines/play-actor": "1.0.0-beta.1",
-    "@xmachines/play-router": "1.0.0-beta.1",
-    "@xmachines/play-signals": "1.0.0-beta.1",
-    "xstate": "^5.28.0"
+    "@xmachines/play-actor": "1.0.0-beta.11",
+    "@xmachines/play-router": "1.0.0-beta.11",
+    "@xmachines/play-signals": "1.0.0-beta.11",
+    "xstate": "^5.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.3.3",
-    "typescript": "^5.7.0"
+    "@tanstack/react-router": "^1.167.5",
+    "@types/node": "^25.5.0",
+    "@xmachines/shared": "1.0.0-beta.11",
+    "jsdom": "^29.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.166.7",
-    "react": "^18.2.0 || ^19.0.0",
-    "react-dom": "^18.2.0 || ^19.0.0",
-    "xstate": "^5.28.0"
-  },
-  "publishConfig": {
-    "access": "public"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "xstate": "^5.0.0"
   }
 }

package/.oxfmtrc.json

@@ -1,3 +0,0 @@
-{
-  "extends": ["@xmachines/shared/oxfmt"]
-}

package/.oxlintrc.json

@@ -1,3 +0,0 @@
-{
-  "extends": ["@xmachines/shared/oxlint"]
-}

package/examples/demo/README.md

@@ -1,100 +0,0 @@
-# TanStack React Router Demo
-
-React + TanStack Router demonstration of Play's actor-authoritative routing and rendering model.
-
-## What This Demonstrates
-
-- Shared auth machine reused without framework-specific business logic
-- `PlayRouterProvider` renderer-based integration with TanStack Router
-- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Non-browser invariant tests plus browser E2E coverage
-
-## Running the Demo
-
-From this directory (`packages/play-tanstack-react-router/examples/demo`):
-
-```bash
-npm install
-npm run dev
-```
-
-Open `http://localhost:3000`.
-
-## Step-by-Step Code Flow
-
-This demo uses provider-based integration centered on `PlayRouterProvider` and a route map generated from the machine:
-
-1. `src/main.tsx` mounts `<App />`.
-2. `src/App.tsx` creates/starts the actor from shared machine + catalog.
-3. `src/App.tsx` builds `routeMap` from `extractMachineRoutes(authMachine)` + `createRouteMapFromTree(routeTree)`.
-4. `PlayRouterProvider` bridges TanStack Router to the actor and renders `Shell` via `renderer(actor, router)`.
-5. `Shell` renders `PlayRenderer`, header/nav, and debug panel from actor state.
-6. Tests in `test/` and `test/browser*/` validate invariant and runtime behavior.
-
-```tsx
-// src/App.tsx (shape)
-const routeTree = extractMachineRoutes(authMachine);
-const routeMap = createRouteMapFromTree(routeTree);
-
-return (
-	<PlayRouterProvider
-		actor={actor}
-		router={router}
-		routeMap={routeMap}
-		renderer={(currentActor, currentRouter) => (
-			<Shell actor={currentActor} router={currentRouter} />
-		)}
-	/>
-);
-```
-
-```tsx
-// src/components/Login.tsx (shape)
-<button onClick={() => actor.send({ type: "auth.login", username, password })}>Login</button>
-```
-
-Shared business logic comes from the common demo machine/catalog module (`authMachine` and `catalog`), so routing decisions remain machine-driven and framework-independent.
-
-## Key Files
-
-- `src/main.tsx` - React entry point that mounts `<App />`
-- `src/App.tsx` - actor lifecycle, route-map creation, provider wiring, and `Shell` rendering
-- `src/components/` - UI components that send actor events and render state-driven views
-- `test/actor-authority.test.ts` - actor authority and guarded navigation behavior
-- `test/strict-separation.test.ts` - machine/view infrastructure separation contracts
-- `test/browser-e2e/auth-flow.browser.test.tsx` - canonical browser auth flow
-- `test/browser/` - extended browser checks for URL sync, history behavior, and route event flow
-
-## 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 (e2e browser config)
-npm run test:browser:full  # Full browser test config run
-npm run test:e2e       # Alias to test:browser
-```
-
-## Verification
-
-Run the core invariant checks referenced by this demo docs:
-
-```bash
-npm run test:vitest -- test/actor-authority.test.ts test/strict-separation.test.ts
-npm run test:browser
-```
-
-Manual sanity flow:
-
-1. Run `npm run dev` and open `http://localhost:3000`.
-2. Attempt protected navigation while logged out and confirm guard-driven behavior.
-3. Log in, then confirm route and view updates stay in sync.
-
-## Learn More
-
-- [TanStack React Router package README](../../README.md)
-- [Solid Router demo README](../../../play-solid-router/examples/demo/README.md)
-- [TanStack Solid Router demo README](../../../play-tanstack-solid-router/examples/demo/README.md)