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

package/src/extract-params.ts

@@ -0,0 +1,75 @@
+/**
+ * Parameter extraction utilities using URLPattern API
+ *
+ * Provides robust parameter extraction from URL paths and query strings.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract route parameters from URL path based on route pattern using URLPattern API
+ *
+ * @param pathname - Actual URL path (e.g., "/profile/123")
+ * @param pattern - Route pattern with params (e.g., "/profile/:userId")
+ * @returns Object with extracted parameters
+ *
+ * @example
+ * ```typescript
+ * extractParams("/profile/123", "/profile/:userId")
+ * // Returns: { userId: "123" }
+ *
+ * extractParams("/api/123", "/api/:id(\\d+)")
+ * // Returns: { id: "123" }
+ * // Validates numeric constraint via URLPattern
+ *
+ * extractParams("/docs/intro", "/docs/*")
+ * // Returns: { "0": "intro" }
+ * ```
+ */
+export function extractParams(pathname: string, pattern: string): Record<string, string> {
+	// Reuse existing implementation from signal-synced-history.ts
+	// URLPattern-based extraction with :param syntax
+	const params: Record<string, string> = {};
+
+	// Parse pattern and pathname to extract named segments
+	const patternParts = pattern.split("/").filter(Boolean);
+	const pathParts = pathname.split("/").filter(Boolean);
+
+	for (let i = 0; i < patternParts.length; i++) {
+		const patternPart = patternParts[i];
+		const pathPart = pathParts[i];
+
+		if (patternPart.startsWith(":")) {
+			const paramName = patternPart.slice(1).replace("?", "");
+			if (pathPart) {
+				params[paramName] = decodeURIComponent(pathPart);
+			}
+		}
+	}
+
+	return params;
+}
+
+/**
+ * Extract query parameters from search string
+ *
+ * @param search - Query string with or without leading ? (e.g., "?tab=settings" or "tab=settings")
+ * @returns Object mapping query parameter names to values
+ *
+ * @example
+ * ```typescript
+ * extractQueryParams("?tab=settings&theme=dark")
+ * // Returns: { tab: "settings", theme: "dark" }
+ *
+ * extractQueryParams("q=hello%20world")
+ * // Returns: { q: "hello world" } (auto-decoded)
+ * ```
+ */
+export function extractQueryParams(search: string): Record<string, string> {
+	const params = new URLSearchParams(search);
+	const result: Record<string, string> = {};
+	params.forEach((value, key) => {
+		result[key] = value;
+	});
+	return result;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @xmachines/play-tanstack-react-router
+ *
+ * TanStack Router adapter for XMachines Play architecture.
+ * Synchronizes browser URL with actor state through passive infrastructure.
+ *
+ * @packageDocumentation
+ */
+
+// New exports (primary API - RouterBridge pattern)
+export { TanStackReactRouterBridge } from "./tanstack-router-bridge.js";
+export { RouteMap, createRouteMapFromTree } from "./route-map.js";
+export { extractParams, extractQueryParams } from "./extract-params.js";
+export type { RouteMapping } from "./route-map.js";
+export type { TanStackRouterLike } from "./tanstack-router-bridge.js";
+
+// TanStack Router integration (React-only)
+export {
+	PlayRouterProvider,
+	type PlayRouterProviderProps,
+	type TanStackRouterInstance,
+} from "./play-router-provider.js";
+
+// Re-export shared utilities for convenience
+export { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+
+// Core routing utilities
+export type { RouteNavigateEvent } from "./types.js";
+
+// Re-exports from protocols
+export type { RouterBridge, PlayRouteEvent } from "@xmachines/play-router";

package/src/play-router-provider.tsx

@@ -0,0 +1,46 @@
+/**
+ * PlayRouterProvider — React convenience wrapper for TanStackReactRouterBridge
+ *
+ * Creates and connects a TanStackReactRouterBridge in a React component lifecycle.
+ * Actor state drives router navigation; router events send play.route to actor.
+ *
+ * @example
+ * ```tsx
+ * <PlayRouterProvider
+ *   actor={actor}
+ *   router={router}
+ *   routeMap={routeMap}
+ *   renderer={(currentActor, currentRouter) => {
+ *     void currentRouter;
+ *     return <PlayRenderer actor={currentActor} components={components} />;
+ *   }}
+ * />
+ * ```
+ */
+import { useEffect, type ReactNode } from "react";
+import type { AbstractActor, Routable, Viewable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+import { TanStackReactRouterBridge } from "./tanstack-router-bridge.js";
+import type { RouteMap } from "./route-map.js";
+
+export type TanStackRouterInstance = ConstructorParameters<typeof TanStackReactRouterBridge>[0];
+
+export interface PlayRouterProviderProps {
+	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
+	router: TanStackRouterInstance;
+	routeMap: RouteMap;
+	renderer: (
+		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
+		router: TanStackRouterInstance,
+	) => ReactNode;
+}
+
+export function PlayRouterProvider({ actor, router, routeMap, renderer }: PlayRouterProviderProps) {
+	useEffect(() => {
+		const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+		bridge.connect();
+		return () => bridge.disconnect();
+	}, [actor, router, routeMap]);
+
+	return <>{renderer(actor, router)}</>;
+}

package/src/route-map.ts

@@ -0,0 +1,158 @@
+/**
+ * RouteMap - Bidirectional mapping between state IDs and route paths
+ *
+ * Provides efficient lookup for:
+ * - State ID → Path (actor state changes → router navigation)
+ * - Path → State ID (router navigation → actor events)
+ *
+ * Supports both static paths and parameterized paths with :param syntax.
+ *
+ * @packageDocumentation
+ */
+
+import type { RouteTree, RouteNode } from "@xmachines/play-router";
+
+/**
+ * Mapping between state machine state ID and router path
+ */
+export interface RouteMapping {
+	/** State ID from state machine (e.g., "settings.profile") */
+	stateId: string;
+	/** Router path with optional parameters (e.g., "/settings/:section?") */
+	path: string;
+}
+
+/**
+ * Bidirectional route mapper with pattern matching support
+ *
+ * Maps between state IDs (XMachines actor) and paths (router).
+ * Handles both exact matches (static paths) and pattern matches (parameterized paths).
+ *
+ * @example
+ * ```typescript
+ * const routes: RouteMapping[] = [
+ *   { stateId: "home", path: "/" },
+ *   { stateId: "profile", path: "/profile/:userId" },
+ *   { stateId: "settings", path: "/settings/:section?" }
+ * ];
+ *
+ * const routeMap = new RouteMap(routes);
+ *
+ * routeMap.getStateIdByPath("/profile/123");  // "profile"
+ * routeMap.getPathByStateId("home");           // "/"
+ * ```
+ */
+export class RouteMap {
+	private stateIdToPath: Map<string, string>;
+	private pathToStateId: Map<string, string>;
+	private patterns: Array<{ pattern: RegExp; stateId: string; path: string }>;
+
+	/**
+	 * Create RouteMap from route mappings
+	 *
+	 * @param routes - Array of state ID → path mappings
+	 */
+	constructor(routes: RouteMapping[]) {
+		this.stateIdToPath = new Map();
+		this.pathToStateId = new Map();
+		this.patterns = [];
+
+		for (const { stateId, path } of routes) {
+			this.stateIdToPath.set(stateId, path);
+
+			// Check if path has parameters
+			if (path.includes(":")) {
+				// Convert :param and :param? to regex
+				const pattern = path
+					.replace(/\/:[^/]+\?/g, "(?:/([^/]+))?") // Optional params with optional slash
+					.replace(/:[^/]+/g, "([^/]+)"); // Required params
+				this.patterns.push({
+					pattern: new RegExp(`^${pattern}$`),
+					stateId,
+					path,
+				});
+			} else {
+				// Exact match for static paths
+				this.pathToStateId.set(path, stateId);
+			}
+		}
+	}
+
+	/**
+	 * Get state ID from router path
+	 *
+	 * Tries exact match first, then pattern match for parameterized paths.
+	 *
+	 * @param path - Router path (e.g., "/profile/123")
+	 * @returns State ID or null if no match
+	 *
+	 * @example
+	 * ```typescript
+	 * routeMap.getStateIdByPath("/");             // "home" (exact match)
+	 * routeMap.getStateIdByPath("/profile/123");  // "profile" (pattern match)
+	 * ```
+	 */
+	getStateIdByPath(path: string): string | null {
+		// Try exact match first
+		const exactMatch = this.pathToStateId.get(path);
+		if (exactMatch) return exactMatch;
+
+		// Try pattern match
+		for (const { pattern, stateId } of this.patterns) {
+			if (pattern.test(path)) return stateId;
+		}
+
+		return null;
+	}
+
+	/**
+	 * Get router path from state ID
+	 *
+	 * Returns the route pattern with parameter placeholders (not substituted).
+	 *
+	 * @param stateId - State machine state ID
+	 * @returns Router path or null if no match
+	 *
+	 * @example
+	 * ```typescript
+	 * routeMap.getPathByStateId("home");     // "/"
+	 * routeMap.getPathByStateId("profile");  // "/profile/:userId"
+	 * ```
+	 */
+	getPathByStateId(stateId: string): string | null {
+		return this.stateIdToPath.get(stateId) || null;
+	}
+}
+
+/**
+ * Create RouteMap from RouteTree
+ *
+ * Converts XMachines route tree to RouteMap for use with router adapters.
+ *
+ * @param routeTree - Route tree from extractMachineRoutes()
+ * @returns RouteMap instance
+ *
+ * @example
+ * ```typescript
+ * import { extractMachineRoutes } from '@xmachines/play-router';
+ * import { createRouteMapFromTree } from '@xmachines/play-tanstack-react-router';
+ *
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMapFromTree(routeTree);
+ * ```
+ */
+export function createRouteMapFromTree(routeTree: RouteTree): RouteMap {
+	const routes: RouteMapping[] = [];
+
+	function traverse(node: RouteNode) {
+		if (node.id && node.path) {
+			routes.push({ stateId: node.id, path: node.path });
+		}
+		if (node.children) {
+			node.children.forEach(traverse);
+		}
+	}
+
+	traverse(routeTree.root);
+	return new RouteMap(routes);
+}

package/src/tanstack-router-bridge.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 class TanStackReactRouterBridge extends RouterBridgeBase {
+	private routerUnsubscribe: (() => void) | null = 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(
+		private readonly router: TanStackRouterLike,
+		actor: AbstractActor<AnyActorLogic> & Routable,
+		routeMap: RouteMap,
+	) {
+		// Adapt RouteMap's null returns to undefined for RouterBridgeBase compatibility
+		super(actor, {
+			getStateIdByPath: (path: string) => routeMap.getStateIdByPath(path) ?? undefined,
+			getPathByStateId: (id: string) => routeMap.getPathByStateId(id) ?? undefined,
+		});
+	}
+
+	protected navigateRouter(path: string): void {
+		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.
+	 */
+	protected override getInitialRouterPath(): string | null {
+		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.
+	 */
+	protected watchRouterChanges(): void {
+		this.routerUnsubscribe = this.router.history.subscribe(
+			({ location }: { location: { pathname: string; search?: string } }) => {
+				this.syncActorFromRouter(location.pathname, location.search ?? "");
+			},
+		);
+	}
+
+	protected unwatchRouterChanges(): void {
+		this.routerUnsubscribe?.();
+		this.routerUnsubscribe = null;
+	}
+}

package/src/types.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;
+}

package/src/utils.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility barrel exports
+ *
+ * @packageDocumentation
+ */
+
+// Parameter extraction utilities
+export { extractParams, extractQueryParams } from "./extract-params.js";
+
+// RouteMap utilities
+export { RouteMap, createRouteMapFromTree } from "./route-map.js";
+export type { RouteMapping } from "./route-map.js";

package/test/browser/signal-synced-history.browser.test.ts

@@ -0,0 +1,95 @@
+import { test, expect } from "vitest";
+import { Signal } from "@xmachines/play-signals";
+import { SignalSyncedHistory } from "../../src/signal-synced-history.js";
+
+test("SignalSyncedHistory syncs actor route to browser URL", async () => {
+	const currentRoute = new Signal.State("/home");
+
+	const mockActor = {
+		currentRoute,
+		send: () => {},
+	} as any;
+
+	const history = new SignalSyncedHistory(mockActor, "/home");
+
+	// Initial URL should match signal (via memory history)
+	const memoryHistory = history.getHistory();
+	expect(memoryHistory.location.pathname).toBe("/home");
+
+	// Update signal
+	currentRoute.set("/dashboard");
+
+	// Wait for microtask batch
+	await new Promise((resolve) => queueMicrotask(resolve));
+
+	// Memory history should update
+	expect(memoryHistory.location.pathname).toBe("/dashboard");
+
+	history.dispose();
+});
+
+test("Browser back button sends route.navigate event to actor", async () => {
+	const currentRoute = new Signal.State("/page1");
+	const sentEvents: any[] = [];
+
+	const mockActor = {
+		currentRoute,
+		send: (event: any) => {
+			sentEvents.push(event);
+		},
+	} as any;
+
+	// Initialize with matching path to avoid initial sync
+	const history = new SignalSyncedHistory(mockActor, "/page1");
+	const memoryHistory = history.getHistory();
+
+	// Clear any initialization events
+	sentEvents.length = 0;
+
+	// Navigate to page2 through memory history (simulating user navigation)
+	memoryHistory.push("/page2");
+
+	// Wait for navigation
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Verify event sent to actor
+	const navEvents = sentEvents.filter((e) => e.type === "route.navigate");
+	expect(navEvents.length).toBeGreaterThan(0);
+	expect(navEvents[0].path).toBe("/page2");
+
+	// Navigate back
+	memoryHistory.back();
+	await new Promise((resolve) => setTimeout(resolve, 100));
+
+	// Should have sent another event for going back to /page1
+	expect(sentEvents.length).toBeGreaterThan(1);
+
+	history.dispose();
+});
+
+test("SignalSyncedHistory prevents circular updates", async () => {
+	const currentRoute = new Signal.State("/initial");
+	const sentEvents: any[] = [];
+
+	const mockActor = {
+		currentRoute,
+		send: (event: any) => {
+			sentEvents.push(event);
+		},
+	} as any;
+
+	// Initialize with matching path to avoid initial sync
+	const history = new SignalSyncedHistory(mockActor, "/initial");
+
+	// Clear any initialization events
+	sentEvents.length = 0;
+
+	// Update signal directly (actor decision)
+	currentRoute.set("/new-path");
+	await new Promise((resolve) => queueMicrotask(resolve));
+
+	// Should not trigger send events (actor initiated the change)
+	expect(sentEvents.length).toBe(0); // No circular events
+
+	history.dispose();
+});