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

package/examples/demo/src/App.tsx

@@ -0,0 +1,148 @@
+/**
+ * Main Application - Integration Layer
+ *
+ * Demonstrates complete Universal Player Architecture integration:
+ * - Actor Authority: Auth machine guards control navigation
+ * - Passive Infrastructure: Router observes actor.currentRoute signal
+ * - Signal-Only Reactivity: PlayRenderer watches signals for UI updates
+ * - Strict Separation: Business logic (machines/) has zero React imports
+ * - State-Driven Reset: Browser navigation sends events to actor
+ *
+ * This layer wires together business logic (auth-machine), infrastructure
+ * (TanStack Router), and view (React components) while maintaining strict
+ * separation of concerns.
+ */
+
+import "@xmachines/play-router-shared/index.css";
+
+import { useMemo, useEffect } from "react";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
+import type { AbstractActor, Routable, Viewable } from "@xmachines/play-actor";
+import { PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
+import { PlayRenderer } from "@xmachines/play-react";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import { createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { defineComponents } from "@xmachines/play-catalog";
+import type { AnyActorLogic } from "xstate";
+import { authMachine, catalog } from "@xmachines/play-router-shared";
+import { Login } from "./components/Login.js";
+import { Dashboard } from "./components/Dashboard.js";
+import { Home } from "./components/Home.js";
+import { About } from "./components/About.js";
+import { Contact } from "./components/Contact.js";
+import { Settings } from "./components/Settings.js";
+import { Profile } from "./components/Profile.js";
+import { Register } from "./components/Register.js";
+import { Navigation } from "./components/Navigation.js";
+import { DebugPanel } from "./components/DebugPanel.js";
+import { HeaderNav } from "./components/HeaderNav.js";
+
+/**
+ * Define React components matching catalog schema
+ *
+ * Type safety: defineComponents() ensures component props match catalog schemas.
+ * This enforces the contract between business logic (catalog) and view layer (React).
+ */
+const components = defineComponents(catalog, {
+	Login,
+	Dashboard,
+	Home,
+	About,
+	Contact,
+	Settings,
+	Profile,
+	Register,
+	Navigation,
+});
+
+function Shell({
+	actor,
+	router,
+}: {
+	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
+	router: unknown;
+}) {
+	void router;
+
+	return (
+		<div className="demo-app">
+			<header className="demo-header">
+				<h1 className="demo-title">XMachines Play - React Demo</h1>
+				<HeaderNav actor={actor} />
+			</header>
+
+			<main className="demo-content">
+				<PlayRenderer actor={actor} components={components} />
+			</main>
+
+			<DebugPanel actor={actor} />
+		</div>
+	);
+}
+
+/**
+ * Main App component
+ *
+ * Architecture:
+ * 1. Creates actor instance from player factory
+ * 2. Creates route map for path → state ID resolution
+ * 3. Creates TanStack Router
+ * 4. Uses PlayRouterProvider with renderer prop pattern
+ *
+ * Lifecycle:
+ * - Mount: actor.start() → begin state machine execution
+ * - Runtime: PlayRenderer observes actor.currentView signal
+ * - Runtime: Provider subscribes to router changes
+ * - Unmount: actor.stop() → halt machine
+ *
+ * Actor Authority: Auth machine guards decide navigation validity.
+ * Passive Infrastructure: Router reflects actor state, doesn't control it.
+ */
+export function App() {
+	// 1. Create actor
+	const actor = useMemo(() => {
+		const createPlayer = definePlayer({ machine: authMachine, catalog });
+		const actorInstance = createPlayer();
+		actorInstance.start();
+		return actorInstance;
+	}, []);
+
+	// 2. Create route map for path → state ID resolution
+	const routeMap = useMemo(() => {
+		const routeTree = extractMachineRoutes(authMachine);
+		return createRouteMapFromTree(routeTree);
+	}, []);
+
+	// 3. Create TanStack Router (using TanStack's API)
+	const router = useMemo(() => {
+		// TanStack Router manages its own route configuration
+		// Note: In real app, you'd configure TanStack routes separately
+		const rootRoute = createRootRoute();
+		return createRouter({
+			routeTree: rootRoute,
+			defaultPreload: "intent",
+		});
+	}, []);
+
+	// 4. Cleanup on unmount
+	useEffect(() => {
+		return () => {
+			actor.stop();
+		};
+	}, [actor]);
+
+	// 5. Use PlayRouterProvider with renderer prop and structured layout
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => (
+				<Shell actor={currentActor} router={currentRouter} />
+			)}
+		/>
+	);
+}
+
+export default App;

package/examples/demo/src/components/About.tsx

@@ -0,0 +1,49 @@
+/**
+ * About - Public information page
+ *
+ * Demonstrates public route with content display.
+ *
+ * @invariant Passive Infrastructure - Forwards events to actor, doesn't control navigation
+ * @invariant Strict Separation - Zero router imports
+ */
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type AboutProps = InferComponentProps<typeof catalog, "About"> & {
+	send: (event: any) => void;
+};
+
+export function About({ title, send }: AboutProps) {
+	return (
+		<div className="about" style={{ maxWidth: "800px", margin: "50px auto", padding: "20px" }}>
+			<h1>{title}</h1>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "15px" }}>
+				This is a demonstration of the XMachines Play Universal Player Architecture.
+			</p>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "15px" }}>
+				Features demonstrated:
+			</p>
+			<ul style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "30px" }}>
+				<li>State machine-driven navigation</li>
+				<li>Protected routes with guards</li>
+				<li>Framework-agnostic business logic</li>
+				<li>TC39 Signals for reactivity</li>
+			</ul>
+			<button
+				onClick={() => send({ type: "play.route", to: "#home" })}
+				style={{
+					padding: "10px 20px",
+					fontSize: "16px",
+					backgroundColor: "#007bff",
+					color: "white",
+					border: "none",
+					borderRadius: "4px",
+					cursor: "pointer",
+				}}
+			>
+				Back to Home
+			</button>
+		</div>
+	);
+}

package/examples/demo/src/components/Contact.tsx

@@ -0,0 +1,43 @@
+/**
+ * Contact - Public contact form
+ *
+ * Demonstrates public route with user interaction.
+ *
+ * @invariant Passive Infrastructure - Forwards events to actor, doesn't control navigation
+ * @invariant Strict Separation - Zero router imports
+ */
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type ContactProps = InferComponentProps<typeof catalog, "Contact"> & {
+	send: (event: any) => void;
+};
+
+export function Contact({ title, send }: ContactProps) {
+	return (
+		<div
+			className="contact"
+			style={{ maxWidth: "800px", margin: "50px auto", padding: "20px" }}
+		>
+			<h1>{title}</h1>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "15px" }}>
+				For support, please reach out.
+			</p>
+			<button
+				onClick={() => send({ type: "play.route", to: "#home" })}
+				style={{
+					padding: "10px 20px",
+					fontSize: "16px",
+					backgroundColor: "#007bff",
+					color: "white",
+					border: "none",
+					borderRadius: "4px",
+					cursor: "pointer",
+				}}
+			>
+				Back to Home
+			</button>
+		</div>
+	);
+}

package/examples/demo/src/components/Dashboard.tsx

@@ -0,0 +1,46 @@
+/**
+ * Dashboard Component - Passive Infrastructure Layer
+ *
+ * Simplified dashboard for unified auth machine demo.
+ */
+
+import React from "react";
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type DashboardProps = InferComponentProps<typeof catalog, "Dashboard"> & {
+	send: (event: any) => void;
+};
+
+export const Dashboard: React.FC<DashboardProps> = ({ send, welcome }) => {
+	return (
+		<div style={{ maxWidth: "800px", margin: "50px auto", padding: "20px" }}>
+			{welcome && <h1 style={{ marginBottom: "20px" }}>Welcome to the Dashboard!</h1>}
+			<div style={{ marginBottom: "20px" }}>
+				<p style={{ fontSize: "16px", lineHeight: "1.6" }}>
+					This is a protected route - you can only see this because you're logged in.
+				</p>
+				<p style={{ fontSize: "16px", lineHeight: "1.6", marginTop: "10px" }}>
+					Use the navigation in the header to explore other pages.
+				</p>
+			</div>
+
+			<button
+				onClick={() => send({ type: "auth.logout" })}
+				style={{
+					padding: "10px 20px",
+					fontSize: "16px",
+					backgroundColor: "#dc3545",
+					color: "white",
+					border: "none",
+					borderRadius: "4px",
+					cursor: "pointer",
+					marginTop: "20px",
+				}}
+			>
+				Logout
+			</button>
+		</div>
+	);
+};

package/examples/demo/src/components/DebugPanel.tsx

@@ -0,0 +1,68 @@
+import { useEffect, useState } from "react";
+import type { AbstractActor } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+import type { AnyActorLogic } from "xstate";
+
+type RoutableActor = AbstractActor<AnyActorLogic> & {
+	currentRoute: { get(): string | null };
+};
+
+type Snapshot = {
+	value: unknown;
+	context: {
+		isAuthenticated?: boolean;
+	};
+};
+
+interface DebugPanelProps {
+	actor: RoutableActor;
+}
+
+export function DebugPanel({ actor }: DebugPanelProps) {
+	const [state, setState] = useState(String((actor.getSnapshot() as Snapshot).value));
+	const [auth, setAuth] = useState((actor.getSnapshot() as Snapshot).context.isAuthenticated);
+	const [route, setRoute] = useState(actor.currentRoute.get());
+
+	useEffect(() => {
+		const watcher = new Signal.subtle.Watcher(() => {
+			queueMicrotask(() => {
+				for (const signal of watcher.getPending()) {
+					signal.get();
+				}
+
+				const typedSnapshot = actor.getSnapshot() as Snapshot;
+				setState(String(typedSnapshot.value));
+				setAuth(typedSnapshot.context.isAuthenticated);
+				setRoute(actor.currentRoute.get());
+
+				watcher.watch(actor.state);
+				watcher.watch(actor.currentRoute as any);
+			});
+		});
+
+		watcher.watch(actor.state);
+		watcher.watch(actor.currentRoute as any);
+
+		return () => {
+			watcher.unwatch(actor.state);
+			watcher.unwatch(actor.currentRoute as any);
+		};
+	}, [actor]);
+
+	return (
+		<footer className="demo-debug">
+			<h3 className="debug-title">Debug Panel</h3>
+			<div className="debug-state">
+				<span className="debug-item">
+					State: <code>{state}</code>
+				</span>
+				<span className="debug-item">
+					Auth: <code>{String(auth)}</code>
+				</span>
+				<span className="debug-item">
+					Route: <code>{route}</code>
+				</span>
+			</div>
+		</footer>
+	);
+}

package/examples/demo/src/components/HeaderNav.tsx

@@ -0,0 +1,103 @@
+/**
+ * Header Navigation Component
+ *
+ * Reactive navigation that shows/hides links based on authentication state
+ */
+
+import { useState } from "react";
+import { useSignalEffect } from "@xmachines/play-react";
+import type { AbstractActor } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+
+interface HeaderNavProps {
+	actor: AbstractActor<AnyActorLogic>;
+}
+
+export function HeaderNav({ actor }: HeaderNavProps) {
+	type Snapshot = {
+		context: {
+			isAuthenticated?: boolean;
+			username?: string | null;
+		};
+	};
+
+	const [isAuthenticated, setIsAuthenticated] = useState(() => {
+		const snapshot = actor.getSnapshot() as Snapshot;
+		return snapshot.context.isAuthenticated ?? false;
+	});
+
+	const [username, setUsername] = useState(() => {
+		const snapshot = actor.getSnapshot() as Snapshot;
+		return snapshot.context.username || "demo";
+	});
+
+	// Watch actor.state signal for changes
+	useSignalEffect(() => {
+		const snapshot = actor.state.get() as Snapshot;
+		setIsAuthenticated(snapshot.context.isAuthenticated ?? false);
+		setUsername(snapshot.context.username || "demo");
+	});
+
+	return (
+		<nav className="demo-nav" aria-label="Main navigation">
+			<a
+				href="/"
+				onClick={(e) => {
+					e.preventDefault();
+					actor.send({ type: "play.route", to: "#home" });
+				}}
+			>
+				Home
+			</a>
+			<a
+				href="/about"
+				onClick={(e) => {
+					e.preventDefault();
+					actor.send({ type: "play.route", to: "#about" });
+				}}
+			>
+				About
+			</a>
+			<a
+				href="/contact"
+				onClick={(e) => {
+					e.preventDefault();
+					actor.send({ type: "play.route", to: "#contact" });
+				}}
+			>
+				Contact
+			</a>
+			{!isAuthenticated && (
+				<a
+					href="/login"
+					onClick={(e) => {
+						e.preventDefault();
+						actor.send({ type: "play.route", to: "#login" });
+					}}
+				>
+					Login
+				</a>
+			)}
+			{isAuthenticated && (
+				<>
+					<a
+						href={`/profile/${username}`}
+						onClick={(e) => {
+							e.preventDefault();
+							actor.send({
+								type: "play.route",
+								to: "#profile",
+								params: { userId: username },
+							});
+						}}
+					>
+						Profile
+					</a>
+					<button type="button" onClick={() => actor.send({ type: "auth.logout" })}>
+						Logout
+					</button>
+				</>
+			)}
+		</nav>
+	);
+}

package/examples/demo/src/components/Home.tsx

@@ -0,0 +1,41 @@
+/**
+ * Home - Public landing page component
+ */
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type HomeProps = InferComponentProps<typeof catalog, "Home"> & {
+	send: (event: any) => void;
+};
+
+export function Home({ title, send }: HomeProps) {
+	return (
+		<div className="home" style={{ maxWidth: "800px", margin: "50px auto", padding: "20px" }}>
+			<h1>{title}</h1>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "15px" }}>
+				Welcome to the XMachines Play demo application.
+			</p>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "30px" }}>
+				This demonstrates the Universal Player Architecture with React and TanStack Router.
+			</p>
+
+			<div style={{ marginBottom: "20px" }}>
+				<button
+					onClick={() => send({ type: "play.route", to: "#login" })}
+					style={{
+						padding: "10px 20px",
+						fontSize: "16px",
+						backgroundColor: "#007bff",
+						color: "white",
+						border: "none",
+						borderRadius: "4px",
+						cursor: "pointer",
+					}}
+				>
+					Go to Login
+				</button>
+			</div>
+		</div>
+	);
+}

package/examples/demo/src/components/Login.tsx

@@ -0,0 +1,82 @@
+/**
+ * Login Component - Passive Infrastructure Layer
+ *
+ * Simplified login form (username only, no password).
+ *
+ * Demonstrates:
+ * - Passive Infrastructure: Forwards events to actor, doesn't control navigation
+ * - Signal-Only Reactivity: No business logic in component (only UI state)
+ * - Strict Separation: Zero router imports - actor decides navigation
+ *
+ * @invariant Passive Infrastructure - Component never imports @tanstack/react-router
+ * @invariant Actor Authority - Login validation happens in actor guards, not here
+ */
+
+import React, { useState, type FormEvent } from "react";
+
+/**
+ * Login props (inferred from catalog)
+ */
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type LoginProps = InferComponentProps<typeof catalog, "Login"> & {
+	send: (event: any) => void;
+};
+
+/**
+ * Simplified login form - username only (no password for demo)
+ */
+export const Login: React.FC<LoginProps> = ({ send, title = "Login" }) => {
+	const [username, setUsername] = useState("");
+
+	const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+		e.preventDefault();
+
+		// Forward to actor - let business logic decide what happens
+		send({
+			type: "auth.login",
+			username,
+		});
+	};
+
+	return (
+		<div style={{ maxWidth: "400px", margin: "50px auto", padding: "20px" }}>
+			<h1>{title}</h1>
+			<form onSubmit={handleSubmit}>
+				<div style={{ marginBottom: "15px" }}>
+					<label htmlFor="username" style={{ display: "block", marginBottom: "5px" }}>
+						Username
+					</label>
+					<input
+						type="text"
+						id="username"
+						value={username}
+						onChange={(e) => setUsername((e.target as HTMLInputElement).value)}
+						style={{ width: "100%", padding: "8px", fontSize: "16px" }}
+						placeholder="Enter any username"
+						required
+					/>
+				</div>
+				<button
+					type="submit"
+					style={{
+						width: "100%",
+						padding: "10px",
+						fontSize: "16px",
+						backgroundColor: "#007bff",
+						color: "white",
+						border: "none",
+						borderRadius: "4px",
+						cursor: "pointer",
+					}}
+				>
+					Log In
+				</button>
+			</form>
+			<p style={{ marginTop: "15px", fontSize: "14px", color: "#666" }}>
+				Enter any username - no password required for demo
+			</p>
+		</div>
+	);
+};