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

package/examples/demo/docs/ARCHITECTURE.md

@@ -0,0 +1,643 @@
+# Demo Application Architecture
+
+**Target reading time:** 15 minutes
+
+This document provides a line-by-line walkthrough of the demo application's architecture, showing how the Universal Player Architecture implements all 5 architectural invariants.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Data Flow](#data-flow)
+3. [File-by-File Explanation](#file-by-file-explanation)
+4. [Key Patterns](#key-patterns)
+5. [Verification](#verification)
+
+---
+
+## Overview
+
+### What This Demo Proves
+
+This demo validates **5 architectural invariants** that define the Universal Player Architecture:
+
+1. **Actor Authority** - Actor guards control navigation, infrastructure obeys
+2. **Strict Separation** - Business logic has zero UI framework imports
+3. **Signal-Only Reactivity** - React rendering driven by signals, not React state
+4. **Passive Infrastructure** - Components forward events, don't control navigation
+5. **State-Driven Reset** - Browser back button sends event to actor for validation
+
+### Tech Stack
+
+- **Business Logic:** XState v5 state machines (`@xmachines/play-xstate`)
+- **Reactive Substrate:** TC39 Signals (`@xmachines/play-signals`)
+- **Router Integration:** TanStack Router (`@xmachines/play-tanstack-react-router`)
+- **View Renderer:** React 18 (`@xmachines/play-react`)
+- **UI Schema:** Zod catalog (`@xmachines/play-catalog`)
+
+### Project Structure
+
+```
+examples/demo-app/
+├── src/
+│   ├── machines/           # Business logic (framework-agnostic)
+│   │   ├── auth-machine.ts # XState machine with guards
+│   │   └── catalog.ts      # Type-safe component schemas
+│   ├── components/         # React UI (Passive Infrastructure)
+│   │   ├── LoginForm.tsx   # Forwards auth.login event
+│   │   └── Dashboard.tsx   # Forwards auth.logout event
+│   └── App.tsx             # Integration layer (router + renderer)
+├── test/
+│   └── invariants/         # Automated invariant validation
+└── docs/
+    ├── ARCHITECTURE.md     # This file
+    └── SWAP-REACT.md       # Framework swapping guide
+```
+
+---
+
+## Data Flow
+
+### User Action → State Transition Flow
+
+```
+User clicks "Log In" button
+  ↓
+LoginForm.tsx forwards event via send()                    [Passive Infrastructure]
+  ↓
+actor.send({ type: "auth.login", username, password })
+  ↓
+XState machine processes event
+  ↓
+Guard checks if transition is valid                        [Actor Authority]
+  ↓
+Context updated: { isAuthenticated: true }
+  ↓
+State transition: loggedOut → dashboard
+  ↓
+Signal emits new value
+  ↓
+useSignalEffect detects change                             [Signal-Only Reactivity]
+  ↓
+PlayRenderer triggers React re-render
+  ↓
+SignalSyncedHistory observes actor.currentRoute signal (derived from state)
+  ↓
+Browser URL updates to /dashboard                          [Passive Infrastructure]
+  ↓
+React renders Dashboard component with new props
+```
+
+**Key Insight:** The actor decides everything. Infrastructure (router, renderer) observes and reacts.
+
+---
+
+## File-by-File Explanation
+
+### 1. `src/machines/auth-machine.ts` - Business Logic Layer
+
+**Purpose:** Defines authentication state machine with guards controlling navigation.
+
+**Key Code:**
+
+```typescript
+// Invariant: Strict Separation
+// ZERO React or TanStack Router imports - business logic is framework-agnostic
+import { createMachine, assign } from "xstate";
+
+interface AuthContext {
+	isAuthenticated: boolean;
+	username: string | null;
+	routeParams: Record<string, string>;
+	queryParams: Record<string, string>;
+}
+
+type AuthEvent =
+	| { type: "play.route"; to: string }
+	| { type: "auth.login"; username: string; password: string }
+	| { type: "auth.logout" };
+
+export const authMachine = createMachine({
+	id: "auth",
+	initial: "loggedOut",
+	context: {
+		isAuthenticated: false,
+		username: null,
+		routeParams: {},
+		queryParams: {},
+	},
+	states: {
+		loggedOut: {
+			meta: {
+				route: "/",
+				// Invariant: Strict Separation
+				// View structure defined in metadata, not JSX
+				view: {
+					component: "LoginForm",
+					props: { title: "Please Log In" },
+				},
+			},
+			on: {
+				"auth.login": {
+					target: "loggedIn",
+					actions: assign({
+						isAuthenticated: true,
+						username: ({ event }) => event.username,
+					}),
+				},
+			},
+		},
+		loggedIn: {
+			meta: {
+				route: "/dashboard",
+				view: {
+					component: "Dashboard",
+					props: { welcome: true },
+				},
+			},
+			// Invariant: Actor Authority
+			// Always-guard validates state entry - can I BE in this state?
+			always: [
+				{
+					target: "loggedOut",
+					guard: ({ context }) => !context.isAuthenticated,
+				},
+			],
+			on: {
+				"auth.logout": {
+					target: "loggedOut",
+					actions: assign({
+						isAuthenticated: false,
+						username: null,
+					}),
+				},
+			},
+		},
+	},
+});
+```
+
+**What This Demonstrates:**
+
+- **Actor Authority:** Always-guard `({ context }) => !context.isAuthenticated` automatically redirects to loggedOut state when authentication is lost
+- **Strict Separation:** No React imports - state machine is pure business logic
+- **State-Driven Reset:** Machine processes play.route events from browser back/forward for validation
+
+**Verification:**
+
+```bash
+# Verify zero React imports
+grep -n "from ['\"']react" src/machines/auth-machine.ts
+# (No output = passes)
+```
+
+---
+
+### 2. `src/machines/catalog.ts` - Type-Safe UI Schema
+
+**Purpose:** Defines component prop schemas using Zod for runtime validation.
+
+**Key Code:**
+
+```typescript
+// Invariant: Strict Separation
+// Catalog is framework-agnostic - no React imports
+import { z } from "zod";
+import { defineCatalog } from "@xmachines/play-catalog";
+
+export const catalog = defineCatalog({
+	LoginForm: z.object({
+		title: z.string(),
+	}),
+	Dashboard: z.object({
+		welcome: z.boolean(),
+	}),
+});
+```
+
+**What This Demonstrates:**
+
+- **Strict Separation:** Catalog has zero React imports - props are inferred by renderer
+- **Type Safety:** Zod schemas provide runtime validation and compile-time type inference
+- **Framework Agnostic:** Same catalog works with React, Vue, Svelte, or any renderer
+
+**Verification:**
+
+```bash
+# Verify zero React imports
+grep -n "from ['\"']react" src/machines/catalog.ts
+# (No output = passes)
+```
+
+---
+
+### 3. `src/components/LoginForm.tsx` - Passive Infrastructure Layer
+
+**Purpose:** React component that forwards credentials to actor without controlling navigation.
+
+**Key Code:**
+
+```typescript
+import React, { useState, type FormEvent } from "react";
+
+interface LoginFormProps {
+	send: (event: any) => void;
+	title: string;
+}
+
+export const LoginForm: React.FC<LoginFormProps> = ({ send, title }) => {
+	// Local UI state ONLY (not business logic)
+	const [username, setUsername] = useState("");
+	const [password, setPassword] = useState("");
+
+	const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+		e.preventDefault();
+
+		// Invariant: Passive Infrastructure
+		// Forward event to actor, let actor decide validity
+		send({
+			type: "auth.login",
+			username,
+			password,
+		});
+	};
+
+	return (
+		<div>
+			<h1>{title}</h1>
+			<form onSubmit={handleSubmit}>
+				<input
+					type="text"
+					value={username}
+					onChange={(e) => setUsername(e.target.value)}
+					required
+				/>
+				<input
+					type="password"
+					value={password}
+					onChange={(e) => setPassword(e.target.value)}
+					required
+				/>
+				<button type="submit">Log In</button>
+			</form>
+		</div>
+	);
+};
+```
+
+**What This Demonstrates:**
+
+- **Passive Infrastructure:** Component forwards `auth.login` event via `send()`, doesn't control navigation
+- **Signal-Only Reactivity:** Business state comes from actor, not React state (username/password are ephemeral form inputs)
+- **Strict Separation:** Zero router imports - component doesn't know about TanStack Router
+
+**Verification:**
+
+```bash
+# Verify zero router imports
+grep -n "@tanstack/react-router" src/components/LoginForm.tsx
+# (No output = passes)
+```
+
+---
+
+### 4. `src/components/Dashboard.tsx` - Protected Route Component
+
+**Purpose:** Displays dashboard content and forwards logout event to actor.
+
+**Key Code:**
+
+```typescript
+import React from "react";
+
+interface DashboardProps {
+	send: (event: any) => void;
+	welcome: boolean;
+}
+
+export const Dashboard: React.FC<DashboardProps> = ({ send, welcome }) => {
+	const handleLogout = () => {
+		// Invariant: Passive Infrastructure
+		// Forward event to actor
+		send({ type: "auth.logout" });
+	};
+
+	return (
+		<div>
+			{welcome && <h1>Welcome to the Dashboard!</h1>}
+			<p>
+				This is a protected route - you can only see this because you're logged
+				in.
+			</p>
+			<button onClick={handleLogout}>Logout</button>
+		</div>
+	);
+};
+```
+
+**What This Demonstrates:**
+
+- **Passive Infrastructure:** Component forwards `auth.logout` event, doesn't navigate directly
+- **Actor Authority:** Access control happens in actor guard, not component logic
+
+**Verification:**
+
+```bash
+# Verify zero router imports
+grep -n "@tanstack/react-router" src/components/Dashboard.tsx
+# (No output = passes)
+```
+
+---
+
+### 5. `src/App.tsx` - Integration Layer
+
+**Purpose:** Wires together actor, router, and renderer.
+
+**Key Code:**
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { createPlayRouter } from "@xmachines/play-tanstack-react-router";
+import { PlayRenderer } from "@xmachines/play-react";
+import { defineComponents } from "@xmachines/play-catalog";
+import { authMachine } from "./machines/auth-machine";
+import { catalog } from "./machines/catalog";
+import { LoginForm } from "./components/LoginForm";
+import { Dashboard } from "./components/Dashboard";
+
+// Define component implementations
+const components = defineComponents(catalog, {
+	LoginForm,
+	Dashboard,
+});
+
+// Create player factory
+const createPlayer = definePlayer({
+	machine: authMachine,
+	catalog,
+});
+
+function App() {
+	// Create actor instance
+	const actor = createPlayer();
+
+	// Start actor
+	actor.start();
+
+	// Create router that syncs with actor state
+	// Invariant: Passive Infrastructure
+	// Router observes actor state, sends play.route events on browser back/forward
+	const router = createPlayRouter({
+		actor,
+	});
+
+	return (
+		<>
+			{/* Invariant: Signal-Only Reactivity */}
+			{/* PlayRenderer uses useSignalEffect to observe actor signals */}
+			<PlayRenderer actor={actor} components={components} />
+		</>
+	);
+}
+
+export default App;
+```
+
+**What This Demonstrates:**
+
+- **Signal-Only Reactivity:** `PlayRenderer` uses `useSignalEffect` to observe actor signals
+- **Passive Infrastructure:** Router created with `createPlayRouter({ actor })` - router observes, doesn't control
+- **Actor Authority:** Actor is the single source of truth - router and renderer react to actor state
+
+**Flow:**
+
+1. `createPlayer()` creates actor factory from machine + catalog
+2. `actor.start()` initializes state machine
+3. `createPlayRouter({ actor })` creates `SignalSyncedHistory` that:
+    - Observes `actor.state` signal via `Signal.subtle.Watcher`
+    - Updates browser URL when actor changes state
+    - Sends `play.route` event to actor when browser back/forward pressed
+4. `PlayRenderer` observes `actor.state` signal and renders matching component
+
+---
+
+## Key Patterns
+
+### Pattern 1: Actor Authority (Guard-Based Navigation)
+
+**Code Location:** `src/machines/auth-machine.ts`
+
+```typescript
+loggedIn: {
+  meta: { route: "/dashboard" },
+  // Always-guard validates state entry
+  always: [
+    {
+      target: "loggedOut",
+      guard: ({ context }) => !context.isAuthenticated
+    }
+  ]
+}
+```
+
+**How It Works:**
+
+- Always-guard checks: "Can I BE in this state given current context?"
+- If `!isAuthenticated`, automatically transitions to loggedOut
+- Guards validate state invariants, not event properties
+- See [demo-app/auth-machine.ts](../src/machines/auth-machine.ts) for full implementation using `formatPlayRouteTransitions`
+
+**Test:** `test/invariants/actor-authority.test.ts` - Attempts to navigate to `/dashboard` while logged out, verifies guard rejects
+
+---
+
+### Pattern 2: meta.view Definition (Strict Separation)
+
+**Code Location:** `src/machines/auth-machine.ts` lines 55-63
+
+```typescript
+meta: {
+  route: "/",
+  view: {
+    component: "LoginForm",
+    props: { title: "Please Log In" },
+  },
+}
+```
+
+**How It Works:**
+
+- View structure defined declaratively in state machine metadata
+- Component name is a string reference (not JSX import)
+- Props are plain data (not React elements)
+- Renderer resolves component name to actual component via catalog
+
+**Test:** `test/invariants/strict-separation.test.ts` - Verifies zero React imports in `auth-machine.ts` and `catalog.ts`
+
+---
+
+### Pattern 3: Signal Observation (Signal-Only Reactivity)
+
+**Code Location:** `packages/play-react/src/PlayRenderer.tsx` (simplified)
+
+```typescript
+function PlayRenderer({ actor, components }) {
+	const [, setTick] = useState(0);
+
+	useSignalEffect(() => {
+		// Observe actor.state signal
+		const currentState = actor.state.get();
+		// Trigger React re-render
+		setTick((t) => t + 1);
+	});
+
+	const currentState = actor.state.get();
+	const view = currentState.meta?.view;
+	const Component = components[view.component];
+
+	return <Component send={actor.send.bind(actor)} {...view.props} />;
+}
+```
+
+**How It Works:**
+
+- `useSignalEffect` uses `Signal.subtle.Watcher` to observe `actor.state` signal
+- When signal changes, React is triggered via `setTick`
+- Business state lives in actor, not React state
+
+**Test:** `test/invariants/signal-only.test.ts` - Verifies `PlayRenderer` uses `useSignalEffect`
+
+---
+
+### Pattern 4: Event Forwarding (Passive Infrastructure)
+
+**Code Location:** `src/components/LoginForm.tsx` lines 54-64
+
+```typescript
+const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+	e.preventDefault();
+	send({ type: "auth.login", username, password });
+};
+```
+
+**How It Works:**
+
+- Component receives `send` function via props (bound to actor)
+- Component forwards event to actor without knowing actor internals
+- Actor processes event and decides outcome
+
+**Test:** `test/invariants/passive-infra.test.ts` - Verifies components have zero router imports, use `send()` for events
+
+---
+
+### Pattern 5: Navigation Handling (State-Driven Reset)
+
+**Code Location:** `packages/play-tanstack-react-router/src/SignalSyncedHistory.ts` (simplified)
+
+```typescript
+class SignalSyncedHistory {
+	constructor(actor) {
+		// Listen to browser popstate (back/forward)
+		window.addEventListener("popstate", () => {
+			const newPath = window.location.pathname;
+			// Send event to actor for validation
+			actor.send({ type: "play.route", to: newPath });
+		});
+
+		// Observe actor's currentRoute signal (derived from state)
+		const watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			// Update browser URL if actor changed route
+			if (route) window.history.pushState({}, "", route);
+		});
+	}
+}
+```
+
+**How It Works:**
+
+- Browser back/forward triggers `popstate` event
+- SignalSyncedHistory sends `play.route` event to actor
+- Actor processes event - always-guards validate state entry
+- If guards allow, state updates and signal emits
+- SignalSyncedHistory observes signal and updates browser URL
+
+**Test:** `test/invariants/state-driven.test.ts` - Sends `play.route` event to simulate browser back, verifies actor processes it
+
+---
+
+## Verification
+
+### Automated Tests
+
+Run all invariant validation tests:
+
+```bash
+cd examples/demo-app
+npm test
+```
+
+Expected output:
+
+```
+✔ DEMO-02: Actor Authority - Guards reject invalid navigation
+✔ DEMO-03: Strict Separation - Business logic has zero React imports
+✔ DEMO-04: State-Driven Reset - Browser back sends event to actor
+✔ DEMO-05: Passive Infrastructure - Components never import TanStack Router
+✔ DEMO-06: Signal-Only Reactivity - PlayRenderer uses signals not React state
+
+ℹ tests 5
+ℹ pass 5
+ℹ fail 0
+```
+
+### Manual Verification
+
+1. **Actor Authority:**
+
+    ```bash
+    npm run dev
+    # Visit http://localhost:3000/dashboard directly (while logged out)
+    # Verify: URL stays at / or redirects (guard rejected)
+    ```
+
+2. **Strict Separation:**
+
+    ```bash
+    grep -rn "from ['\"']react" src/machines/
+    # Expected: no output (zero React imports)
+    ```
+
+3. **Passive Infrastructure:**
+
+    ```bash
+    grep -rn "@tanstack/react-router" src/components/
+    # Expected: no output (zero router imports)
+    ```
+
+4. **Signal-Only Reactivity:**
+
+    ```bash
+    grep -n "useSignalEffect" packages/play-react/src/PlayRenderer.tsx
+    # Expected: line number showing useSignalEffect usage
+    ```
+
+5. **State-Driven Reset:**
+    ```bash
+    # Run demo, login, click browser back button
+    # Observe: actor.send({ type: "play.route", to: "/" }) logged
+    ```
+
+---
+
+## Next Steps
+
+- **Understand Invariants:** Read the RFC specification for detailed explanations
+- **Swap Frameworks:** Read [SWAP-REACT.md](./SWAP-REACT.md) to see how to replace React with Vue/Svelte
+- **Build Your Own:** Use this demo as a template for your application
+
+---
+
+**Questions?** See the RFC specification for deeper invariant explanations and rationale.