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

package/examples/demo/docs/SWAP-REACT.md

@@ -0,0 +1,635 @@
+# Swapping React for Vue or Svelte
+
+**Proof of DEMO-06:** This guide demonstrates that swapping React for Vue or Svelte requires **zero changes to business logic** - only the view renderer and component implementations change.
+
+---
+
+## Table of Contents
+
+1. [What Needs to Change](#what-needs-to-change)
+2. [What Stays the Same](#what-stays-the-same)
+3. [Vue Example](#vue-example)
+4. [Svelte Example](#svelte-example)
+5. [Why This Works](#why-this-works)
+
+---
+
+## What Needs to Change
+
+| Layer                         | React                   | Vue                            | Svelte                            |
+| ----------------------------- | ----------------------- | ------------------------------ | --------------------------------- |
+| **Business Logic**            | ✅ No changes           | ✅ No changes                  | ✅ No changes                     |
+| **State Machine**             | ✅ No changes           | ✅ No changes                  | ✅ No changes                     |
+| **Component Catalog**         | ✅ No changes           | ✅ No changes                  | ✅ No changes                     |
+| **Router Integration**        | ✅ No changes           | ✅ No changes                  | ✅ No changes                     |
+| **View Renderer**             | `@xmachines/play-react` | `@xmachines/play-vue` (future) | `@xmachines/play-svelte` (future) |
+| **Component Implementations** | `.tsx` files            | `.vue` files                   | `.svelte` files                   |
+
+**Key Insight:** Only the view layer changes. Business logic, state machine, catalog, and router integration are framework-agnostic.
+
+---
+
+## What Stays the Same
+
+### 1. State Machine (100% Unchanged)
+
+```typescript
+// src/machines/auth-machine.ts - IDENTICAL for React, Vue, Svelte
+import { createMachine, assign } from "xstate";
+
+export const authMachine = createMachine({
+	id: "auth",
+	initial: "loggedOut",
+	context: {
+		isAuthenticated: false,
+		username: null,
+		routeParams: {},
+		queryParams: {},
+	},
+	states: {
+		loggedOut: {
+			meta: {
+				route: "/",
+				view: {
+					component: "LoginForm", // String reference, not framework-specific
+					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 },
+				},
+			},
+			// Always-guard validates state entry
+			always: [
+				{
+					target: "loggedOut",
+					guard: ({ context }) => !context.isAuthenticated,
+				},
+			],
+			on: {
+				"auth.logout": {
+					target: "loggedOut",
+					actions: assign({
+						isAuthenticated: false,
+						username: null,
+					}),
+				},
+			},
+		},
+	},
+});
+```
+
+**Why It's Unchanged:**
+
+- No React imports - machine is pure XState
+- View structure in `meta.view` is plain data
+- Component names are strings, not JSX imports
+- Guards, actions, context are framework-agnostic
+
+---
+
+### 2. Component Catalog (100% Unchanged)
+
+```typescript
+// src/machines/catalog.ts - IDENTICAL for React, Vue, Svelte
+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(),
+	}),
+});
+```
+
+**Why It's Unchanged:**
+
+- No React imports - catalog uses Zod schemas
+- Props are plain data structures
+- Zod validation is framework-agnostic
+
+---
+
+### 3. Router Integration (100% Unchanged)
+
+```typescript
+// Integration code - IDENTICAL for React, Vue, Svelte
+import { definePlayer } from "@xmachines/play-xstate";
+import { createPlayRouter } from "@xmachines/play-tanstack-react-router";
+
+const createPlayer = definePlayer({
+	machine: authMachine,
+	catalog,
+});
+
+const actor = createPlayer();
+actor.start();
+
+const router = createPlayRouter({ actor });
+```
+
+**Why It's Unchanged:**
+
+- `definePlayer` is framework-agnostic
+- `createPlayRouter` observes actor signals, doesn't care about view framework
+- Router sync happens via signals, not React-specific hooks
+
+---
+
+## Vue Example
+
+### Installing Vue Renderer (Future)
+
+```bash
+npm install @xmachines/play-vue vue
+```
+
+### Vue LoginForm Component
+
+```vue
+<!-- src/components/LoginForm.vue -->
+<script setup lang="ts">
+import { ref } from "vue";
+
+// Props from catalog
+interface Props {
+	send: (event: any) => void;
+	title: string;
+}
+
+const props = defineProps<Props>();
+
+// Local UI state ONLY (not business logic)
+const username = ref("");
+const password = ref("");
+
+const handleSubmit = () => {
+	// Passive Infrastructure: Forward event to actor
+	props.send({
+		type: "auth.login",
+		username: username.value,
+		password: password.value,
+	});
+};
+</script>
+
+<template>
+	<div style="max-width: 400px; margin: 50px auto; padding: 20px">
+		<h1>{{ title }}</h1>
+		<form @submit.prevent="handleSubmit">
+			<div style="margin-bottom: 15px">
+				<label for="username" style="display: block; margin-bottom: 5px"> Username </label>
+				<input
+					type="text"
+					id="username"
+					v-model="username"
+					style="width: 100%; padding: 8px; font-size: 16px"
+					required
+				/>
+			</div>
+			<div style="margin-bottom: 15px">
+				<label for="password" style="display: block; margin-bottom: 5px"> Password </label>
+				<input
+					type="password"
+					id="password"
+					v-model="password"
+					style="width: 100%; padding: 8px; font-size: 16px"
+					required
+				/>
+			</div>
+			<button
+				type="submit"
+				style="
+					width: 100%;
+					padding: 10px;
+					font-size: 16px;
+					background-color: #007bff;
+					color: white;
+					border: none;
+					border-radius: 4px;
+					cursor: pointer;
+				"
+			>
+				Log In
+			</button>
+		</form>
+		<p style="margin-top: 15px; font-size: 14px; color: #666">
+			Demo credentials: any username/password
+		</p>
+	</div>
+</template>
+```
+
+**Key Similarities to React:**
+
+- Component receives `send` function via props (same interface)
+- Component forwards `auth.login` event (same event structure)
+- Local form state managed by Vue (`ref` instead of `useState`)
+- Business logic remains in actor - component just forwards events
+
+---
+
+### Vue Dashboard Component
+
+```vue
+<!-- src/components/Dashboard.vue -->
+<script setup lang="ts">
+interface Props {
+	send: (event: any) => void;
+	welcome: boolean;
+}
+
+const props = defineProps<Props>();
+
+const handleLogout = () => {
+	// Passive Infrastructure: Forward event to actor
+	props.send({ type: "auth.logout" });
+};
+</script>
+
+<template>
+	<div style="max-width: 800px; margin: 50px auto; padding: 20px">
+		<h1 v-if="welcome" style="margin-bottom: 20px">Welcome to the Dashboard!</h1>
+		<div style="margin-bottom: 20px">
+			<p style="font-size: 16px; line-height: 1.6">
+				This is a protected route - you can only see this because you're logged in.
+			</p>
+			<p style="font-size: 16px; line-height: 1.6; margin-top: 10px">
+				The authentication machine's guard protects this route from logged-out users,
+				demonstrating the <strong>Actor Authority</strong> invariant.
+			</p>
+		</div>
+		<button
+			@click="handleLogout"
+			style="
+				padding: 10px 20px;
+				font-size: 16px;
+				background-color: #dc3545;
+				color: white;
+				border: none;
+				border-radius: 4px;
+				cursor: pointer;
+			"
+		>
+			Logout
+		</button>
+	</div>
+</template>
+```
+
+---
+
+### Vue App Integration
+
+```typescript
+// src/App.vue
+<script setup lang="ts">
+import { definePlayer } from "@xmachines/play-xstate";
+import { createPlayRouter } from "@xmachines/play-tanstack-react-router";
+import { PlayRenderer } from "@xmachines/play-vue"; // Vue renderer
+import { defineComponents } from "@xmachines/play-catalog";
+import { authMachine } from "./machines/auth-machine";
+import { catalog } from "./machines/catalog";
+import LoginForm from "./components/LoginForm.vue";
+import Dashboard from "./components/Dashboard.vue";
+
+// Define component implementations
+const components = defineComponents(catalog, {
+	LoginForm,
+	Dashboard,
+});
+
+// Create player factory
+const createPlayer = definePlayer({
+	machine: authMachine,
+	catalog,
+});
+
+// Create actor instance
+const actor = createPlayer();
+actor.start();
+
+// Create router
+const router = createPlayRouter({ actor });
+</script>
+
+<template>
+	<!-- PlayRenderer uses Vue's reactivity system to observe actor signals -->
+	<PlayRenderer :actor="actor" :components="components" />
+</template>
+```
+
+**Key Changes from React:**
+
+- Import `@xmachines/play-vue` instead of `@xmachines/play-react`
+- Component files are `.vue` instead of `.tsx`
+- Vue template syntax (`v-model`, `@click`) instead of JSX
+
+**What Stayed the Same:**
+
+- `definePlayer({ machine, catalog })` - identical
+- `createPlayRouter({ actor })` - identical
+- Business logic in `authMachine` - unchanged
+- Component prop interface (`send`, `title`, `welcome`) - identical
+
+---
+
+## Svelte Example
+
+### Installing Svelte Renderer (Future)
+
+```bash
+npm install @xmachines/play-svelte svelte
+```
+
+### Svelte LoginForm Component
+
+```svelte
+<!-- src/components/LoginForm.svelte -->
+<script lang="ts">
+	// Props from catalog
+	export let send: (event: any) => void;
+	export let title: string;
+
+	// Local UI state ONLY (not business logic)
+	let username = "";
+	let password = "";
+
+	const handleSubmit = (e: Event) => {
+		e.preventDefault();
+
+		// Passive Infrastructure: Forward event to actor
+		send({
+			type: "auth.login",
+			username,
+			password,
+		});
+	};
+</script>
+
+<div style="max-width: 400px; margin: 50px auto; padding: 20px">
+	<h1>{title}</h1>
+	<form on:submit={handleSubmit}>
+		<div style="margin-bottom: 15px">
+			<label for="username" style="display: block; margin-bottom: 5px">
+				Username
+			</label>
+			<input
+				type="text"
+				id="username"
+				bind:value={username}
+				style="width: 100%; padding: 8px; font-size: 16px"
+				required
+			/>
+		</div>
+		<div style="margin-bottom: 15px">
+			<label for="password" style="display: block; margin-bottom: 5px">
+				Password
+			</label>
+			<input
+				type="password"
+				id="password"
+				bind:value={password}
+				style="width: 100%; padding: 8px; font-size: 16px"
+				required
+			/>
+		</div>
+		<button
+			type="submit"
+			style="width: 100%; padding: 10px; font-size: 16px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer;"
+		>
+			Log In
+		</button>
+	</form>
+	<p style="margin-top: 15px; font-size: 14px; color: #666">
+		Demo credentials: any username/password
+	</p>
+</div>
+```
+
+**Key Similarities to React/Vue:**
+
+- Component receives `send` function via props (same interface)
+- Component forwards `auth.login` event (same event structure)
+- Local form state managed by Svelte (`let` instead of `useState`/`ref`)
+- Business logic remains in actor - component just forwards events
+
+---
+
+### Svelte Dashboard Component
+
+```svelte
+<!-- src/components/Dashboard.svelte -->
+<script lang="ts">
+	export let send: (event: any) => void;
+	export let welcome: boolean;
+
+	const handleLogout = () => {
+		// Passive Infrastructure: Forward event to actor
+		send({ type: "auth.logout" });
+	};
+</script>
+
+<div style="max-width: 800px; margin: 50px auto; padding: 20px">
+	{#if welcome}
+		<h1 style="margin-bottom: 20px">Welcome to the Dashboard!</h1>
+	{/if}
+	<div style="margin-bottom: 20px">
+		<p style="font-size: 16px; line-height: 1.6">
+			This is a protected route - you can only see this because you're logged
+			in.
+		</p>
+		<p style="font-size: 16px; line-height: 1.6; margin-top: 10px">
+			The authentication machine's guard protects this route from logged-out
+			users, demonstrating the <strong>Actor Authority</strong> invariant.
+		</p>
+	</div>
+	<button
+		on:click={handleLogout}
+		style="padding: 10px 20px; font-size: 16px; background-color: #dc3545; color: white; border: none; border-radius: 4px; cursor: pointer;"
+	>
+		Logout
+	</button>
+</div>
+```
+
+---
+
+### Svelte App Integration
+
+```svelte
+<!-- src/App.svelte -->
+<script lang="ts">
+	import { definePlayer } from "@xmachines/play-xstate";
+	import { createPlayRouter } from "@xmachines/play-tanstack-react-router";
+	import { PlayRenderer } from "@xmachines/play-svelte"; // Svelte renderer
+	import { defineComponents } from "@xmachines/play-catalog";
+	import { authMachine } from "./machines/auth-machine";
+	import { catalog } from "./machines/catalog";
+	import LoginForm from "./components/LoginForm.svelte";
+	import Dashboard from "./components/Dashboard.svelte";
+
+	// Define component implementations
+	const components = defineComponents(catalog, {
+		LoginForm,
+		Dashboard,
+	});
+
+	// Create player factory
+	const createPlayer = definePlayer({
+		machine: authMachine,
+		catalog,
+	});
+
+	// Create actor instance
+	const actor = createPlayer();
+	actor.start();
+
+	// Create router
+	const router = createPlayRouter({ actor });
+</script>
+
+<!-- PlayRenderer uses Svelte stores to observe actor signals -->
+<PlayRenderer {actor} {components} />
+```
+
+**Key Changes from React/Vue:**
+
+- Import `@xmachines/play-svelte` instead of `@xmachines/play-react`
+- Component files are `.svelte` instead of `.tsx`/`.vue`
+- Svelte template syntax (`bind:value`, `on:click`) instead of JSX/Vue
+
+**What Stayed the Same:**
+
+- `definePlayer({ machine, catalog })` - identical
+- `createPlayRouter({ actor })` - identical
+- Business logic in `authMachine` - unchanged
+- Component prop interface (`send`, `title`, `welcome`) - identical
+
+---
+
+## Why This Works
+
+### 1. Strict Separation Invariant
+
+**Business logic has zero framework imports.**
+
+`auth-machine.ts` and `catalog.ts` have no React, Vue, or Svelte imports. They use XState and Zod - both framework-agnostic libraries.
+
+**Verification:**
+
+```bash
+grep -rn "from ['\"']react\|from ['\"']vue\|from ['\"']svelte" src/machines/
+# Expected: no output (zero framework imports)
+```
+
+---
+
+### 2. Signal-Only Reactivity Invariant
+
+**Business state lives in actor signals, not framework-specific state.**
+
+- React: `useSignalEffect` observes `actor.state` signal
+- Vue: Vue's reactivity system observes `actor.state` signal via `watchEffect`
+- Svelte: Svelte stores observe `actor.state` signal via `derived`
+
+All three frameworks observe the **same signal** - the actor's state signal. Framework-specific reactivity is only for rendering, not business logic.
+
+---
+
+### 3. Passive Infrastructure Invariant
+
+**Components forward events via `send()`, don't control navigation.**
+
+All three implementations:
+
+```typescript
+// React
+send({ type: "auth.login", username, password });
+
+// Vue
+props.send({ type: "auth.login", username: username.value, password: password.value });
+
+// Svelte
+send({ type: "auth.login", username, password });
+```
+
+Same event structure. Same `send` function interface. Actor processes event identically regardless of framework.
+
+---
+
+### 4. meta.view Pattern
+
+**View structure defined in metadata, not framework-specific code.**
+
+```typescript
+meta: {
+  view: {
+    component: "LoginForm",  // String reference
+    props: { title: "Please Log In" },
+  },
+}
+```
+
+- React renderer resolves `"LoginForm"` → `LoginForm.tsx`
+- Vue renderer resolves `"LoginForm"` → `LoginForm.vue`
+- Svelte renderer resolves `"LoginForm"` → `LoginForm.svelte`
+
+Same metadata structure. Framework-specific resolution happens at runtime by renderer.
+
+---
+
+## Summary
+
+### What Changes
+
+| Item             | React                   | Vue                   | Svelte                   |
+| ---------------- | ----------------------- | --------------------- | ------------------------ |
+| Renderer package | `@xmachines/play-react` | `@xmachines/play-vue` | `@xmachines/play-svelte` |
+| Component files  | `.tsx`                  | `.vue`                | `.svelte`                |
+| Template syntax  | JSX                     | Vue templates         | Svelte templates         |
+| Local state      | `useState`              | `ref`                 | `let`                    |
+
+### What Stays the Same (100% Unchanged)
+
+- ✅ State machine definition (`auth-machine.ts`)
+- ✅ Component catalog (`catalog.ts`)
+- ✅ Guards, actions, context
+- ✅ Event types (`auth.login`, `auth.logout`, `play.route`)
+- ✅ Component prop interface (`send`, `title`, `welcome`)
+- ✅ Router integration (`createPlayRouter`)
+- ✅ Business logic, validation, authentication flow
+
+---
+
+## Try It Yourself
+
+1. **Clone this demo** and verify React works
+2. **Implement Vue components** following patterns above
+3. **Swap renderer** in `App.vue`
+4. **Run `npm run dev`** - everything works!
+5. **Verify tests still pass** - invariants proven
+
+**Result:** Business logic unchanged. Framework swap complete.
+
+---
+
+**Questions?** Read [ARCHITECTURE.md](./ARCHITECTURE.md) for line-by-line code walkthrough or the RFC specification for invariant explanations.

package/examples/demo/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>XMachines Play - React Demo</title>
+		<meta
+			name="description"
+			content="Universal Player Architecture demonstration with authentication flow"
+		/>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

package/examples/demo/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xmachines/play-tanstack-react-router-demo",
+  "version": "1.0.0-beta.1",
+  "private": true,
+  "description": "Universal Player Architecture demonstration with authentication flow",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:vitest": "vitest run",
+    "test:browser": "NODE_OPTIONS='--max-old-space-size=8192' vitest run --config vitest.config.e2e.browser.ts",
+    "test:browser:full": "NODE_OPTIONS='--max-old-space-size=8192' vitest run --config vitest.browser.config.ts",
+    "test:e2e": "npm run test:browser"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "^1.166.7",
+    "@xmachines/play": "1.0.0-beta.1",
+    "@xmachines/play-catalog": "1.0.0-beta.1",
+    "@xmachines/play-react": "1.0.0-beta.1",
+    "@xmachines/play-router": "1.0.0-beta.1",
+    "@xmachines/play-router-shared": "1.0.0-beta.1",
+    "@xmachines/play-tanstack-react-router": "1.0.0-beta.1",
+    "@xmachines/play-xstate": "1.0.0-beta.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "xstate": "^5.28.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "jsdom": "^28.1.0",
+    "typescript": "^5.7.0",
+    "vite": "^7.3.1"
+  }
+}