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

package/dist/route-map.js.map

@@ -0,0 +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"}

package/dist/tanstack-router-bridge.d.ts

@@ -0,0 +1,115 @@
+/**
+ * TanStackReactRouterBridge - TanStack React Router adapter implementing RouterBridge protocol
+ *
+ * Provides bidirectional synchronization between XMachines actor state
+ * and TanStack React Router. Extends RouterBridgeBase which handles all
+ * common lifecycle, sync, and circular-update prevention logic.
+ *
+ * Only the 3 TanStack-specific methods need to be implemented:
+ * - navigateRouter: calls router.navigate({ to: path })
+ * - watchRouterChanges: subscribes to router.history for ALL navigation types
+ * - unwatchRouterChanges: calls the unsubscribe function
+ *
+ * Architectural Invariants:
+ * - INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+ * - Actor validates all navigation via guards before URL changes
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { createRouter } from '@tanstack/react-router';
+ * import { definePlayer } from '@xmachines/play-xstate';
+ * import { TanStackReactRouterBridge, createRouteMapFromTree } from '@xmachines/play-tanstack-react-router';
+ *
+ * const router = createRouter({ routes });
+ * const actor = definePlayer({ machine, catalog })();
+ * const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
+ *
+ * const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+ * bridge.connect();
+ *
+ * // Cleanup on unmount
+ * return () => bridge.disconnect();
+ * ```
+ */
+import { RouterBridgeBase } from "@xmachines/play-router";
+import type { AbstractActor, Routable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+import type { RouteMap } from "./route-map.js";
+export type TanStackRouterLike = {
+    navigate(args: {
+        to: string;
+    }): void;
+    state?: {
+        location?: {
+            pathname?: string;
+        };
+    };
+    history: {
+        subscribe(handler: (event: {
+            location: {
+                pathname: string;
+                search?: string;
+            };
+        }) => void): () => void;
+    };
+};
+/**
+ * TanStack React Router adapter implementing RouterBridge protocol via RouterBridgeBase
+ *
+ * @remarks
+ * Extends RouterBridgeBase to handle all common lifecycle and sync logic.
+ * Only 3 TanStack-specific methods are implemented here.
+ *
+ * Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
+ * back/forward browser navigation (popstate events) are also captured. The
+ * router.subscribe("onBeforeLoad") approach only works when TanStack's
+ * Transitioner component is mounted (i.e. inside a full <RouterProvider>).
+ * Since this bridge is used without <RouterProvider>, we must subscribe to
+ * the underlying history object directly — which is exactly what Transitioner
+ * does internally: `router.history.subscribe(router.load)`.
+ *
+ * Architectural Invariants:
+ * - INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+ * - Actor validates all navigation via guards before URL changes
+ *
+ * @example
+ * ```typescript
+ * const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+ * bridge.connect();
+ * return () => bridge.disconnect();
+ * ```
+ */
+export declare class TanStackReactRouterBridge extends RouterBridgeBase {
+    private readonly router;
+    private routerUnsubscribe;
+    /**
+     * Create TanStack React Router bridge
+     *
+     * @param router - TanStack React Router instance
+     * @param actor - XMachines actor instance
+     * @param routeMap - Bidirectional mapping between state IDs and paths
+     */
+    constructor(router: TanStackRouterLike, actor: AbstractActor<AnyActorLogic> & Routable, routeMap: RouteMap);
+    protected navigateRouter(path: string): void;
+    /**
+     * Read the router's current pathname for initial sync.
+     *
+     * Called once in connect() to handle cold-load / deep-link scenarios where
+     * the URL differs from the actor's initial state.
+     */
+    protected getInitialRouterPath(): string | null;
+    /**
+     * Subscribe to ALL navigation events via router.history.
+     *
+     * router.history.subscribe fires for PUSH, POP, BACK, FORWARD, REPLACE, and GO —
+     * covering both link clicks and browser back/forward button presses.
+     *
+     * The subscriber callback receives { location, action } where location is the
+     * new history location with pathname and search already updated.
+     */
+    protected watchRouterChanges(): void;
+    protected unwatchRouterChanges(): void;
+}
+//# sourceMappingURL=tanstack-router-bridge.d.ts.map

package/dist/tanstack-router-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanstack-router-bridge.d.ts","sourceRoot":"","sources":["../src/tanstack-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,MAAM,kBAAkB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC7C,OAAO,EAAE;QACR,SAAS,CACR,OAAO,EAAE,CAAC,KAAK,EAAE;YAAE,QAAQ,EAAE;gBAAE,QAAQ,EAAE,MAAM,CAAC;gBAAC,MAAM,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,KAAK,IAAI,GAC3E,MAAM,IAAI,CAAC;KACd,CAAC;CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,yBAA0B,SAAQ,gBAAgB;IAW7D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVxB,OAAO,CAAC,iBAAiB,CAA6B;IAEtD;;;;;;OAMG;gBAEe,MAAM,EAAE,kBAAkB,EAC3C,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,QAAQ;IASnB,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;;;;OAKG;cACgB,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAIxD;;;;;;;;OAQG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAQpC,SAAS,CAAC,oBAAoB,IAAI,IAAI;CAItC"}

package/dist/tanstack-router-bridge.js

@@ -0,0 +1,112 @@
+/**
+ * TanStackReactRouterBridge - TanStack React Router adapter implementing RouterBridge protocol
+ *
+ * Provides bidirectional synchronization between XMachines actor state
+ * and TanStack React Router. Extends RouterBridgeBase which handles all
+ * common lifecycle, sync, and circular-update prevention logic.
+ *
+ * Only the 3 TanStack-specific methods need to be implemented:
+ * - navigateRouter: calls router.navigate({ to: path })
+ * - watchRouterChanges: subscribes to router.history for ALL navigation types
+ * - unwatchRouterChanges: calls the unsubscribe function
+ *
+ * Architectural Invariants:
+ * - INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+ * - Actor validates all navigation via guards before URL changes
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { createRouter } from '@tanstack/react-router';
+ * import { definePlayer } from '@xmachines/play-xstate';
+ * import { TanStackReactRouterBridge, createRouteMapFromTree } from '@xmachines/play-tanstack-react-router';
+ *
+ * const router = createRouter({ routes });
+ * const actor = definePlayer({ machine, catalog })();
+ * const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
+ *
+ * const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+ * bridge.connect();
+ *
+ * // Cleanup on unmount
+ * return () => bridge.disconnect();
+ * ```
+ */
+import { RouterBridgeBase } from "@xmachines/play-router";
+/**
+ * TanStack React Router adapter implementing RouterBridge protocol via RouterBridgeBase
+ *
+ * @remarks
+ * Extends RouterBridgeBase to handle all common lifecycle and sync logic.
+ * Only 3 TanStack-specific methods are implemented here.
+ *
+ * Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
+ * back/forward browser navigation (popstate events) are also captured. The
+ * router.subscribe("onBeforeLoad") approach only works when TanStack's
+ * Transitioner component is mounted (i.e. inside a full <RouterProvider>).
+ * Since this bridge is used without <RouterProvider>, we must subscribe to
+ * the underlying history object directly — which is exactly what Transitioner
+ * does internally: `router.history.subscribe(router.load)`.
+ *
+ * Architectural Invariants:
+ * - INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+ * - Actor validates all navigation via guards before URL changes
+ *
+ * @example
+ * ```typescript
+ * const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+ * bridge.connect();
+ * return () => bridge.disconnect();
+ * ```
+ */
+export class TanStackReactRouterBridge extends RouterBridgeBase {
+    router;
+    routerUnsubscribe = null;
+    /**
+     * Create TanStack React Router bridge
+     *
+     * @param router - TanStack React Router instance
+     * @param actor - XMachines actor instance
+     * @param routeMap - Bidirectional mapping between state IDs and paths
+     */
+    constructor(router, actor, routeMap) {
+        // Adapt RouteMap's null returns to undefined for RouterBridgeBase compatibility
+        super(actor, {
+            getStateIdByPath: (path) => routeMap.getStateIdByPath(path) ?? undefined,
+            getPathByStateId: (id) => routeMap.getPathByStateId(id) ?? undefined,
+        });
+        this.router = router;
+    }
+    navigateRouter(path) {
+        this.router.navigate({ to: path });
+    }
+    /**
+     * Read the router's current pathname for initial sync.
+     *
+     * Called once in connect() to handle cold-load / deep-link scenarios where
+     * the URL differs from the actor's initial state.
+     */
+    getInitialRouterPath() {
+        return this.router.state?.location?.pathname ?? null;
+    }
+    /**
+     * Subscribe to ALL navigation events via router.history.
+     *
+     * router.history.subscribe fires for PUSH, POP, BACK, FORWARD, REPLACE, and GO —
+     * covering both link clicks and browser back/forward button presses.
+     *
+     * The subscriber callback receives { location, action } where location is the
+     * new history location with pathname and search already updated.
+     */
+    watchRouterChanges() {
+        this.routerUnsubscribe = this.router.history.subscribe(({ location }) => {
+            this.syncActorFromRouter(location.pathname, location.search ?? "");
+        });
+    }
+    unwatchRouterChanges() {
+        this.routerUnsubscribe?.();
+        this.routerUnsubscribe = null;
+    }
+}
+//# sourceMappingURL=tanstack-router-bridge.js.map

package/dist/tanstack-router-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanstack-router-bridge.js","sourceRoot":"","sources":["../src/tanstack-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAe1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,yBAA0B,SAAQ,gBAAgB;IAW5C;IAVV,iBAAiB,GAAwB,IAAI,CAAC;IAEtD;;;;;;OAMG;IACH,YACkB,MAA0B,EAC3C,KAA8C,EAC9C,QAAkB;QAElB,gFAAgF;QAChF,KAAK,CAAC,KAAK,EAAE;YACZ,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,SAAS;YAChF,gBAAgB,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,IAAI,SAAS;SAC5E,CAAC,CAAC;QARc,WAAM,GAAN,MAAM,CAAoB;IAS5C,CAAC;IAES,cAAc,CAAC,IAAY;QACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACgB,oBAAoB;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,IAAI,IAAI,CAAC;IACtD,CAAC;IAED;;;;;;;;OAQG;IACO,kBAAkB;QAC3B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CACrD,CAAC,EAAE,QAAQ,EAAuD,EAAE,EAAE;YACrE,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC,CACD,CAAC;IACH,CAAC;IAES,oBAAoB;QAC7B,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;QAC3B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAC/B,CAAC;CACD"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type definitions for TanStack Router integration with Play Architecture.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Event sent to actor when browser navigates.
+ *
+ * Browser navigation (user clicks link, back/forward button, direct URL entry)
+ * sends this event to the actor. The actor's guards determine if navigation
+ * is allowed based on business logic.
+ *
+ * Invariant: Passive Infrastructure - Router suggests, actor decides validity.
+ *
+ * @example
+ * ```typescript
+ * actor.send({ type: 'route.navigate', path: '/dashboard' });
+ * ```
+ */
+export interface RouteNavigateEvent {
+    /** Event type discriminant (extends XState event pattern) */
+    readonly type: "route.navigate";
+    /** Target route path (may include parameters, e.g., /posts/123) */
+    readonly path: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for TanStack Router integration with Play Architecture.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility barrel exports
+ *
+ * @packageDocumentation
+ */
+export { extractParams, extractQueryParams } from "./extract-params.js";
+export { RouteMap, createRouteMapFromTree } from "./route-map.js";
+export type { RouteMapping } from "./route-map.js";
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGxE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/utils.js

@@ -0,0 +1,10 @@
+/**
+ * Utility barrel exports
+ *
+ * @packageDocumentation
+ */
+// Parameter extraction utilities
+export { extractParams, extractQueryParams } from "./extract-params.js";
+// RouteMap utilities
+export { RouteMap, createRouteMapFromTree } from "./route-map.js";
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iCAAiC;AACjC,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAExE,qBAAqB;AACrB,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC"}

package/examples/demo/README.md

@@ -0,0 +1,100 @@
+# 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)