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

package/examples/demo/docs/INVARIANTS.md

@@ -0,0 +1,461 @@
+# Architectural Invariants Validation
+
+This document explains how the demo application validates each of the 5 architectural invariants that define the Universal Player Architecture.
+
+---
+
+## Table of Contents
+
+1. [Actor Authority](#1-actor-authority)
+2. [Strict Separation](#2-strict-separation)
+3. [Signal-Only Reactivity](#3-signal-only-reactivity)
+4. [Passive Infrastructure](#4-passive-infrastructure)
+5. [State-Driven Reset](#5-state-driven-reset)
+6. [Why These Invariants Matter](#why-these-invariants-matter)
+
+---
+
+## 1. Actor Authority
+
+### What It Means
+
+**The actor controls navigation via guards. Infrastructure obeys actor decisions.**
+
+In traditional web apps, routing libraries control navigation - they decide if a route transition is valid. In Universal Player Architecture, the **actor** decides via guard functions, and infrastructure (router, components) obeys.
+
+### How Demo Proves It
+
+**Code Location:** `src/machines/auth-machine.ts`
+
+```typescript
+dashboard: {
+  meta: { route: "/dashboard" },
+  // Always-guard validates state entry
+  always: [
+    {
+      target: "login",
+      guard: ({ context }) => !context.isAuthenticated
+    }
+  ]
+}
+```
+
+**Proof:**
+
+1. Try to access `/dashboard` while logged out
+2. Always-guard checks: `!context.isAuthenticated` → `true`
+3. Automatic transition to `login` state
+4. Actor Authority: actor decides navigation validity, not the router
+
+**Test Reference:** `test/invariants/actor-authority.test.ts`
+
+```typescript
+// Attempt to access protected route while logged out
+actor.send({ type: "play.route", to: "/dashboard" });
+
+// Always-guard validates: !isAuthenticated → redirect to login
+assert.strictEqual(actor.getSnapshot().matches("login"), true);
+```
+
+**Run Test:**
+
+```bash
+cd examples/demo-app
+npm test -- test/invariants/actor-authority.test.ts
+```
+
+### Why This Matters
+
+- **Security:** Authentication logic lives in actor, not URL patterns
+- **Consistency:** Same guard logic works across all platforms (web, mobile, desktop)
+- **Testability:** Test guards in isolation without DOM or routing libraries
+
+---
+
+## 2. Strict Separation
+
+### What It Means
+
+**Business logic has zero UI framework imports. View structure defined in metadata, not JSX.**
+
+Traditional React apps mix business logic with JSX. In Universal Player Architecture, state machines define view structure declaratively in `meta.view`, with zero React imports.
+
+### How Demo Proves It
+
+**Code Location:** `src/machines/auth-machine.ts` lines 55-63
+
+```typescript
+loggedOut: {
+  meta: {
+    route: "/",
+    // View structure in metadata, not JSX
+    view: {
+      component: "LoginForm",  // String reference, not JSX import
+      props: { title: "Please Log In" },
+    },
+  },
+}
+```
+
+**Proof:**
+
+1. `auth-machine.ts` imports: `createMachine`, `assign` from `xstate` - **no React**
+2. `catalog.ts` imports: `z` from `zod`, `defineCatalog` - **no React**
+3. View structure is plain data: `{ component: "LoginForm", props: {...} }`
+4. Renderer resolves component name at runtime via catalog
+
+**Test Reference:** `test/invariants/strict-separation.test.ts`
+
+```typescript
+const authMachineContent = readFileSync("src/machines/auth-machine.ts", "utf-8");
+const catalogContent = readFileSync("src/machines/catalog.ts", "utf-8");
+
+// Verify no React imports
+const reactImportPattern = /from ['"]react['"]/;
+assert.strictEqual(reactImportPattern.test(authMachineContent), false);
+assert.strictEqual(reactImportPattern.test(catalogContent), false);
+```
+
+**Run Test:**
+
+```bash
+cd examples/demo-app
+npm test -- test/invariants/strict-separation.test.ts
+```
+
+**Manual Verification:**
+
+```bash
+grep -rn "from ['\"']react" src/machines/
+# Expected: no output (zero React imports)
+```
+
+### Why This Matters
+
+- **Framework Agnostic:** Same state machine works with React, Vue, Svelte, or any renderer
+- **Portability:** Business logic runs in Node.js, browser, mobile, desktop without changes
+- **Longevity:** Framework churn doesn't affect business logic
+
+---
+
+## 3. Signal-Only Reactivity
+
+### What It Means
+
+**React rendering driven by signals, not React state for business logic.**
+
+Traditional React apps use `useState` for business state. In Universal Player Architecture, business state lives in actor signals. React observes signals via `useSignalEffect` and only uses `useState` for render triggering.
+
+### How Demo Proves It
+
+**Code Location:** `packages/play-react/src/PlayRenderer.tsx` (simplified)
+
+```typescript
+function PlayRenderer({ actor, components }) {
+	const [, setTick] = useState(0);
+
+	// Observe actor.state signal
+	useSignalEffect(() => {
+		const currentState = actor.state.get();
+		setTick((t) => t + 1); // Trigger React re-render
+	});
+
+	const currentState = actor.state.get();
+	const view = currentState.meta?.view;
+	const Component = components[view.component];
+
+	return <Component send={actor.send.bind(actor)} {...view.props} />;
+}
+```
+
+**Proof:**
+
+1. `PlayRenderer` uses `useSignalEffect` to observe `actor.state` signal
+2. `useState` is used ONLY for render triggering (`setTick`), not business state
+3. Business state comes from `actor.state.get()` - signal, not React state
+4. Components receive `send` function to forward events to actor
+
+**Test Reference:** `test/invariants/signal-only.test.ts`
+
+```typescript
+const playRendererContent = readFileSync("packages/play-react/src/PlayRenderer.tsx", "utf-8");
+
+// PlayRenderer must use useSignalEffect for signal observation
+assert.strictEqual(playRendererContent.includes("useSignalEffect"), true);
+```
+
+**Run Test:**
+
+```bash
+cd examples/demo-app
+npm test -- test/invariants/signal-only.test.ts
+```
+
+### Why This Matters
+
+- **Single Source of Truth:** Business state lives in actor, not duplicated in React state
+- **Consistency:** Signal updates are atomic and synchronous - no race conditions
+- **Debuggability:** Inspect actor state via XState DevTools, not React DevTools
+
+---
+
+## 4. Passive Infrastructure
+
+### What It Means
+
+**Components forward events to actor, don't control navigation. Zero router imports.**
+
+Traditional React components import routing libraries and navigate directly (e.g., `navigate("/dashboard")`). In Universal Player Architecture, components forward events to actor via `send()` and actor decides navigation.
+
+### How Demo Proves It
+
+**Code Location:** `src/components/LoginForm.tsx` lines 54-64
+
+```typescript
+const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+	e.preventDefault();
+
+	// Forward event to actor - component doesn't navigate
+	send({ type: "auth.login", username, password });
+};
+```
+
+**Proof:**
+
+1. `LoginForm.tsx` imports: `React`, `useState`, `FormEvent` - **no router imports**
+2. Component receives `send` function via props (bound to actor)
+3. Submit button forwards `auth.login` event to actor
+4. Actor decides if login is valid and transitions to dashboard state
+5. Router observes actor.currentRoute signal (derived from state) and updates browser URL
+
+**Test Reference:** `test/invariants/passive-infra.test.ts`
+
+```typescript
+const componentsDir = "src/components";
+const files = readdirSync(componentsDir).filter((f) => f.endsWith(".tsx"));
+
+const routerImportPattern = /from ['"]@tanstack\/react-router['"]/;
+
+for (const file of files) {
+	const content = readFileSync(join(componentsDir, file), "utf-8");
+
+	// Verify no TanStack Router imports
+	assert.strictEqual(routerImportPattern.test(content), false);
+
+	// Verify components use send() for event forwarding
+	assert.strictEqual(content.includes("send(") || content.includes("send:"), true);
+}
+```
+
+**Run Test:**
+
+```bash
+cd examples/demo-app
+npm test -- test/invariants/passive-infra.test.ts
+```
+
+**Manual Verification:**
+
+```bash
+grep -rn "@tanstack/react-router" src/components/
+# Expected: no output (zero router imports)
+```
+
+### Why This Matters
+
+- **Testability:** Test components without routing libraries - just pass mock `send` function
+- **Flexibility:** Change routing libraries without touching components
+- **Consistency:** Navigation logic centralized in actor, not scattered across components
+
+---
+
+## 5. State-Driven Reset
+
+### What It Means
+
+**Browser back button sends event to actor for validation. Infrastructure doesn't decide.**
+
+Traditional routers update URL immediately when back button pressed, then components react. In Universal Player Architecture, router sends `play.route` event to actor, actor processes event with always-guards, then state updates.
+
+### How Demo Proves It
+
+**Code Location:** `packages/play-tanstack-react-router/src/SignalSyncedHistory.ts` (simplified)
+
+```typescript
+window.addEventListener("popstate", () => {
+	const newPath = window.location.pathname;
+	// Send event to actor for validation
+	actor.send({ type: "play.route", to: newPath });
+});
+```
+
+**Actor handles event:**
+
+```typescript
+dashboard: {
+	// Always-guard validates state entry
+	always: [
+		{
+			target: "login",
+			guard: ({ context }) => !context.isAuthenticated,
+		},
+	];
+}
+```
+
+**Proof:**
+
+1. User presses browser back button
+2. `popstate` event fires
+3. `SignalSyncedHistory` sends `{ type: "play.route", to: "/" }` to actor
+4. Actor processes event - always-guards validate state entry
+5. If guards allow, state updates
+6. If guards reject, automatic redirect to valid state
+
+**Test Reference:** `test/invariants/state-driven.test.ts`
+
+```typescript
+// Login to dashboard
+actor.send({ type: "auth.login", username: "test", password: "pass" });
+assert.strictEqual(actor.getSnapshot().matches("dashboard"), true);
+
+// Simulate browser back button: send play.route event
+actor.send({ type: "play.route", to: "/" });
+
+// Actor processes event - always-guards validate state entry
+assert.strictEqual(actor.getSnapshot().matches("home"), true);
+```
+
+**Run Test:**
+
+```bash
+cd examples/demo-app
+npm test -- test/invariants/state-driven.test.ts
+```
+
+### Why This Matters
+
+- **Security:** Browser back can't bypass authentication guards
+- **Consistency:** Navigation validation logic centralized in actor
+- **Predictability:** Actor state is single source of truth, not URL
+
+---
+
+## Why These Invariants Matter
+
+### Traditional Approach Problems
+
+**Example: Traditional React + React Router app**
+
+```typescript
+// Component controls navigation directly
+function LoginForm() {
+	const navigate = useNavigate();
+	const [user, setUser] = useState(null);
+
+	const handleLogin = async () => {
+		const result = await api.login(username, password);
+		setUser(result.user); // Business state in React state
+		navigate("/dashboard"); // Component decides navigation
+	};
+
+	return <form onSubmit={handleLogin}>...</form>;
+}
+
+// Protected route check in router config
+<Route
+	path="/dashboard"
+	element={
+		<ProtectedRoute>
+			<Dashboard />
+		</ProtectedRoute>
+	}
+/>;
+```
+
+**Problems:**
+
+1. **No Actor Authority:** `navigate("/dashboard")` bypasses authentication logic
+2. **No Strict Separation:** Business logic (`api.login`, `setUser`) mixed with React
+3. **No Signal-Only Reactivity:** Business state in `useState` - duplicated across components
+4. **No Passive Infrastructure:** Component imports router and navigates directly
+5. **No State-Driven Reset:** Browser back updates URL immediately - component reacts after
+
+### Universal Player Architecture Solution
+
+**Example: This demo app**
+
+```typescript
+// State machine defines behavior
+const authMachine = createMachine({
+	states: {
+		loggedOut: {
+			on: {
+				"auth.login": { target: "loggedIn" },
+			},
+		},
+		loggedIn: {
+			// Always-guard validates state entry
+			always: [
+				{
+					target: "loggedOut",
+					guard: ({ context }) => !context.isAuthenticated,
+				},
+			],
+		},
+	},
+});
+
+// Component forwards events
+function LoginForm({ send }) {
+	const [username, setUsername] = useState("");
+	const [password, setPassword] = useState("");
+
+	const handleSubmit = () => {
+		send({ type: "auth.login", username, password });
+	};
+
+	return <form onSubmit={handleSubmit}>...</form>;
+}
+```
+
+**Benefits:**
+
+1. **Actor Authority:** Always-guard validates state entry - component can't bypass
+2. **Strict Separation:** State machine has zero React imports
+3. **Signal-Only Reactivity:** Business state in actor signals
+4. **Passive Infrastructure:** Component forwards events, doesn't navigate
+5. **State-Driven Reset:** Browser back sends event to actor for validation via always-guards
+
+---
+
+## Running All Tests
+
+Validate all 5 invariants:
+
+```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
+```
+
+---
+
+## Next Steps
+
+- **Line-by-Line Walkthrough:** Read [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed code explanations
+- **Swap Frameworks:** Read [SWAP-REACT.md](./SWAP-REACT.md) to see how business logic remains unchanged when swapping React for Vue/Svelte
+- **Build Your Own:** Use invariant tests as regression protection when building your application