@xmachines/play-xstate 1.0.0-beta.1

package/src/routing/build-url.ts

@@ -0,0 +1,127 @@
+import type { RouteContext } from "./types.js";
+import { isAbsoluteRoute } from "./derive-route.js";
+
+/**
+ * Build full URL from route template and context
+ *
+ * Per CONTEXT.md:
+ * - "currentRoute derivation: Full URL generation including query params, hash, base path"
+ * - "Parameters: String template syntax — /user/:id"
+ * - "Inheritance: relative paths inherit parent route"
+ *
+ * Per RESEARCH.md Pattern 3: Replace :param with context values
+ *
+ * @example
+ * ```typescript
+ * const url = buildRouteUrl('/user/:id', {
+ *   id: '123',
+ *   query: { tab: 'profile' },
+ *   hash: 'section-1'
+ * });
+ * // Result: '/user/123?tab=profile#section-1'
+ * ```
+ *
+ * @param routeTemplate - Route path with :param placeholders
+ * @param context - Route context with parameters, query, hash
+ * @returns Full URL string
+ */
+export const buildRouteUrl = (routeTemplate: string, context: RouteContext = {}): string => {
+	// Handle relative vs absolute paths
+	const basePath = context.basePath || "";
+	const isAbsolute = isAbsoluteRoute(routeTemplate);
+
+	// Build base URL
+	let url = isAbsolute ? routeTemplate : joinPaths(basePath, routeTemplate);
+
+	// Replace :param with context values
+	url = substituteParams(url, context);
+
+	// Append query params from context
+	if (context.query && typeof context.query === "object") {
+		const params = new URLSearchParams(context.query as any);
+		const queryString = params.toString();
+		if (queryString) {
+			url += `?${queryString}`;
+		}
+	}
+
+	// Append hash from context
+	if (context.hash && typeof context.hash === "string") {
+		url += `#${context.hash}`;
+	}
+
+	return url;
+};
+
+/**
+ * Substitute :param placeholders with context values
+ *
+ * Per RESEARCH.md: Replace :param with encodeURIComponent(context[param])
+ *
+ * Supports optional parameters with :param? syntax.
+ * - Optional parameters without values are removed entirely (including the /)
+ * - Required parameters without values log warnings
+ *
+ * Parameter lookup:
+ * - First checks context.routeParams[param] (common pattern in state machines)
+ * - Falls back to context[param] (flat context)
+ *
+ * @param template - URL template with :param or :param? syntax
+ * @param context - Context with parameter values (may have routeParams field)
+ * @returns URL with parameters substituted and double slashes cleaned
+ */
+const substituteParams = (template: string, context: RouteContext): string => {
+	// Replace parameters, handling optional syntax
+	let hasOptionalRemoval = false;
+	const result = template.replace(/:(\w+)(\?)?/g, (_match, param, optional) => {
+		// Check routeParams first (common pattern), then flat context
+		const value = (context as any).routeParams?.[param] ?? context[param];
+
+		// Parameter has a non-empty value - substitute it
+		// For optional params, treat empty string as "no value"
+		if (value !== undefined && value !== null && value !== "") {
+			return encodeURIComponent(String(value));
+		}
+
+		// Optional parameter without value (or empty string) - remove the segment
+		if (optional === "?") {
+			hasOptionalRemoval = true;
+			return ""; // Will leave // in path, cleaned up below
+		}
+
+		// Required parameter missing - warn and use empty string
+		console.warn(`Route parameter '${param}' not found in context. Template: ${template}`);
+		return "";
+	});
+
+	// Clean up double slashes
+	let cleaned = result.replace(/\/+/g, "/");
+
+	// Only remove trailing slash if we removed optional parameters
+	// (preserves trailing slash for required params, which indicates an error)
+	if (hasOptionalRemoval && cleaned.endsWith("/")) {
+		cleaned = cleaned.slice(0, -1);
+	}
+
+	return cleaned;
+};
+
+/**
+ * Join base path and relative path
+ *
+ * Ensures single slash between paths
+ *
+ * @param base - Base path
+ * @param relative - Relative path
+ * @returns Joined path
+ */
+const joinPaths = (base: string, relative: string): string => {
+	// Remove trailing slash from base
+	const normalizedBase = base.replace(/\/$/, "");
+
+	// Remove leading slash from relative
+	const normalizedRelative = relative.replace(/^\//, "");
+
+	// Join with single slash
+	return normalizedBase ? `${normalizedBase}/${normalizedRelative}` : `/${normalizedRelative}`;
+};

package/src/routing/derive-route.ts

@@ -0,0 +1,152 @@
+import type { RouteMetadata, RouteObject } from "./types.js";
+
+/**
+ * Derive route from XState state metadata
+ *
+ * Extracts route URL template from `meta.route` in the active state's metadata.
+ * Supports both string routes (`"/about"`) and object routes with path property
+ * (`{ path: "/about" }`). Returns null for states without route metadata (not
+ * all states need to be routable).
+ *
+ * **Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
+ * routing information from state machine definitions rather than external configuration.
+ * The route is determined by the Actor's current state, not by infrastructure decisions.
+ *
+ * @param stateMeta - State metadata from snapshot.getMeta()
+ * @returns Route path template (may include :params) or null if no route found
+ *
+ * @example
+ * Basic route extraction
+ * ```typescript
+ * import { deriveRoute } from "@xmachines/play-xstate";
+ * import { setup } from "xstate";
+ *
+ * const machine = setup({}).createMachine({
+ *   states: {
+ *     about: {
+ *       meta: { route: "/about", view: { component: "AboutPage" } }
+ *     }
+ *   }
+ * });
+ *
+ * const actor = createActor(machine);
+ * actor.start();
+ * const snapshot = actor.getSnapshot();
+ * const meta = snapshot.getMeta();
+ *
+ * const route = deriveRoute(meta);
+ * console.log(route); // "/about"
+ * ```
+ *
+ * @example
+ * Route with parameters
+ * ```typescript
+ * const machine = setup({}).createMachine({
+ *   states: {
+ *     profile: {
+ *       meta: {
+ *         route: "/profile/:userId",
+ *         view: { component: "ProfilePage", userId: (ctx) => ctx.userId }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * const route = deriveRoute(snapshot.getMeta());
+ * console.log(route); // "/profile/:userId" (template, before substitution)
+ * ```
+ *
+ * @example
+ * Route object format
+ * ```typescript
+ * const machine = setup({}).createMachine({
+ *   states: {
+ *     dashboard: {
+ *       meta: {
+ *         route: { path: "/dashboard" },
+ *         view: { component: "Dashboard" }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * const route = deriveRoute(snapshot.getMeta());
+ * console.log(route); // "/dashboard"
+ * ```
+ *
+ * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
+ * @see {@link buildRouteUrl} for URL construction with parameter substitution
+ * @see {@link isAbsoluteRoute} for checking path absoluteness
+ *
+ * @remarks
+ * This function checks `meta.route` for route definitions. States with `route: {}` config
+ * are routable. Parameter substitution happens via {@link buildRouteUrl}, not in this
+ * function (deriveRoute returns templates).
+ *
+ * **Non-routable States:** States without `meta.route` return `null`. This is intentional—
+ * not all states need routes. For example, intermediate loading states or substates may
+ * not correspond to distinct URLs.
+ */
+export const deriveRoute = (stateMeta: Record<string, any>): string | null => {
+	// Iterate through active state nodes to find route information
+	for (const [_stateId, meta] of Object.entries(stateMeta)) {
+		if (!meta) continue;
+
+		// Check meta.route for routable states
+		if (meta.route) {
+			return normalizeRoute(meta.route);
+		}
+	}
+
+	return null;
+};
+
+/**
+ * Normalize route metadata to string path
+ *
+ * Handles both string and object formats for route definitions, ensuring consistent
+ * string output for URL construction.
+ *
+ * @param route - Route metadata (string or object with path property)
+ * @returns Normalized route path string
+ * @throws {Error} If route format is invalid
+ */
+const normalizeRoute = (route: RouteMetadata): string => {
+	if (typeof route === "string") {
+		return route;
+	}
+
+	// Route object with path property
+	if (route && typeof route === "object" && "path" in route) {
+		return (route as RouteObject).path;
+	}
+
+	throw new Error(
+		`Invalid route metadata: ${JSON.stringify(route)}. Expected string or { path: string }`,
+	);
+};
+
+/**
+ * Check if route path is absolute
+ *
+ * Determines whether a route path is absolute (starts with `/`) or relative.
+ * Absolute paths don't inherit from parent routes, while relative paths can be
+ * composed with parent paths for nested routing.
+ *
+ * @param path - Route path to check
+ * @returns true if path starts with '/', false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isAbsoluteRoute } from "@xmachines/play-xstate";
+ *
+ * console.log(isAbsoluteRoute("/dashboard")); // true
+ * console.log(isAbsoluteRoute("settings"));   // false
+ * console.log(isAbsoluteRoute("./about"));    // false
+ * ```
+ *
+ * @see {@link deriveRoute} for route extraction
+ */
+export const isAbsoluteRoute = (path: string): boolean => {
+	return path.startsWith("/");
+};

package/src/routing/format-play-route-transitions.ts

@@ -0,0 +1,77 @@
+import { assign } from "xstate";
+
+/**
+ * Formats play.route transitions from declarative route configs
+ *
+ * Crawls machine states looking for states with meta.route and generates
+ * transitions that handle `play.route` events by matching event.to to state IDs.
+ *
+ * Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
+ *
+ * Usage:
+ * ```typescript
+ * const machineConfig = {
+ *   id: "myMachine",
+ *   states: {
+ *     home: { id: "home", meta: { route: "/home" } },
+ *     dashboard: { id: "dashboard", meta: { route: "/dashboard" } }
+ *   }
+ * };
+ *
+ * const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+ * ```
+ *
+ * This automatically generates play.route handlers at the root level that:
+ * - Match event.to against state IDs (e.g., event.to === "#home")
+ * - Target the appropriate state
+ * - Assign routeParams and queryParams from the event to context
+ *
+ * @param machineConfig - XState machine config (before createMachine)
+ * @returns Machine config with auto-generated play.route handlers
+ */
+export function formatPlayRouteTransitions(machineConfig: any): any {
+	const routeTransitions: any[] = [];
+
+	const collectRoutes = (states: Record<string, any>, parentPath = "") => {
+		Object.entries(states).forEach(([key, stateConfig]) => {
+			const stateId = stateConfig.id || (parentPath ? `${parentPath}.${key}` : key);
+
+			if (stateConfig.meta?.route && stateConfig.id) {
+				// Generate transition for this routable state
+				const transition = {
+					target: `.${key}`, // Relative target from root
+					guard: ({ event }: { event: any }) => event.to === `#${stateConfig.id}`,
+					reenter: true, // Enable context updates on self-transitions
+					actions: assign({
+						routeParams: ({ event }: { event: any }) => event.params || {},
+						queryParams: ({ event }: { event: any }) => event.query || {},
+					}),
+				};
+
+				routeTransitions.push(transition);
+			}
+
+			// Recursively collect from child states
+			if (stateConfig.states) {
+				collectRoutes(stateConfig.states, stateId);
+			}
+		});
+	};
+
+	if (machineConfig.states) {
+		collectRoutes(machineConfig.states);
+	}
+
+	// Add play.route handler to root if we found any routes
+	if (routeTransitions.length > 0) {
+		return {
+			...machineConfig,
+			on: {
+				...machineConfig.on,
+				"play.route": routeTransitions,
+			},
+		};
+	}
+
+	return machineConfig;
+}

package/src/routing/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Route derivation and URL building utilities
+ *
+ * Provides functions for extracting routes from state metadata
+ * and building full URLs with parameter substitution.
+ *
+ * @packageDocumentation
+ */
+
+export { deriveRoute, isAbsoluteRoute } from "./derive-route.js";
+export { buildRouteUrl } from "./build-url.js";
+export { formatPlayRouteTransitions } from "./format-play-route-transitions.js";
+export type { RouteMetadata, RouteObject, RouteContext } from "./types.js";

package/src/routing/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Route metadata from state machine
+ *
+ * Per CONTEXT.md: Both simple strings and objects supported
+ */
+export type RouteMetadata = string | RouteObject;
+
+/**
+ * Route object with additional metadata
+ */
+export interface RouteObject {
+	/** Route path template (e.g., '/user/:id') */
+	path: string;
+	/** Additional route metadata (title, etc.) */
+	[key: string]: any;
+}
+
+/**
+ * Route build context from machine context
+ */
+export interface RouteContext {
+	/** Base path for relative routes */
+	basePath?: string;
+	/** Route parameters to substitute */
+	[key: string]: any;
+}

package/src/signals/debounce.ts

@@ -0,0 +1,38 @@
+/**
+ * Microtask debouncing for glitch-free signal updates
+ *
+ * Per CONTEXT.md: "Microtask batching for glitch-free guarantee"
+ * Per RESEARCH.md Pattern 5: Updates batch in microtask queue
+ *
+ * Leverages TC39 Signal primitives for proper batching.
+ */
+
+/**
+ * Schedule callback in microtask queue
+ *
+ * Multiple calls in same tick coalesce into single execution.
+ *
+ * @param callback - Function to execute in microtask
+ * @returns Function to cancel scheduled execution
+ */
+export const scheduleMicrotask = (callback: () => void): (() => void) => {
+	let scheduled = false;
+	let cancelled = false;
+
+	const execute = () => {
+		if (!cancelled) {
+			callback();
+		}
+		scheduled = false;
+	};
+
+	if (!scheduled) {
+		scheduled = true;
+		queueMicrotask(execute);
+	}
+
+	// Return cancel function
+	return () => {
+		cancelled = true;
+	};
+};

package/src/signals/index.ts

@@ -0,0 +1,2 @@
+export { StateSignalManager } from "./state-signal.js";
+export { scheduleMicrotask } from "./debounce.js";

package/src/signals/state-signal.ts

@@ -0,0 +1,45 @@
+import { Signal } from "@xmachines/play-signals";
+
+/**
+ * Manage state signal with synchronous updates
+ *
+ * Per CONTEXT.md: "Update timing: On stable states only"
+ * Per RESEARCH.md: Only update when snapshot.status === 'active'
+ *
+ * Note: Previously used microtask batching, but this broke guard redirects.
+ * XState already provides coalescence - if multiple transitions occur in a single send(),
+ * the subscription callback only fires once with the final state.
+ */
+export class StateSignalManager<TSnapshot = any> {
+	private _signal: Signal.State<TSnapshot>;
+
+	constructor(initialSnapshot: TSnapshot) {
+		this._signal = new Signal.State(initialSnapshot);
+	}
+
+	/**
+	 * Get the signal instance
+	 */
+	get signal(): Signal.State<TSnapshot> {
+		return this._signal;
+	}
+
+	/**
+	 * Update signal synchronously
+	 *
+	 * Synchronous updates ensure that guard-triggered redirects are immediately
+	 * visible to router bridges, allowing them to sync the browser URL.
+	 *
+	 * @param snapshot - New snapshot to set
+	 */
+	scheduleUpdate(snapshot: TSnapshot): void {
+		this._signal.set(snapshot);
+	}
+
+	/**
+	 * Cleanup (no-op since we're synchronous now)
+	 */
+	dispose(): void {
+		// No cleanup needed for synchronous updates
+	}
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+import type { AnyStateMachine } from "xstate";
+import type { PlayerActor as PlayerActorClass } from "./player-actor.js";
+
+/**
+ * Configuration for definePlayer()
+ *
+ * Per CONTEXT.md: Single config object with machine, catalog, options
+ */
+export interface PlayerConfig<TMachine extends AnyStateMachine, TCatalog = any> {
+	/** XState v5 state machine */
+	machine: TMachine;
+
+	/** UI component catalog (optional - allows machines without UI) */
+	catalog?: TCatalog;
+
+	/** Lifecycle hooks and configuration */
+	options?: PlayerOptions;
+}
+
+/**
+ * Player lifecycle hooks
+ *
+ * Per CONTEXT.md: Rich set of hooks for observability
+ */
+export interface PlayerOptions {
+	/** Called when actor starts */
+	onStart?: (actor: any) => void;
+
+	/** Called when actor stops */
+	onStop?: (actor: any) => void;
+
+	/** Called on every state transition */
+	onTransition?: (actor: any, prevState: any, nextState: any) => void;
+
+	/** Called when state signal changes */
+	onStateChange?: (actor: any, state: any) => void;
+
+	/** Called on actor errors */
+	onError?: (actor: any, error: Error) => void;
+}
+
+/**
+ * Factory function returned by definePlayer()
+ *
+ * Per CONTEXT.md: Factory supports creating multiple actor instances
+ */
+export type PlayerFactory<TInput = any> = (input?: TInput) => PlayerActorClass<any>;

package/test/derive-route.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "vitest";
+import { deriveRoute } from "../src/routing/derive-route.js";
+
+describe("deriveRoute", () => {
+	describe("meta.route pattern", () => {
+		test("extracts path from meta.route", () => {
+			const meta = {
+				"root.about": {
+					route: "/about",
+					view: { component: "About" },
+				},
+			};
+			const result = deriveRoute(meta);
+			expect(result).toBe("/about");
+		});
+
+		test("handles multiple states and finds first with meta.route", () => {
+			const meta = {
+				root: {},
+				"root.authenticated": {},
+				"root.authenticated.home": {
+					route: "/home",
+					view: { component: "Home" },
+				},
+			};
+			const result = deriveRoute(meta);
+			expect(result).toBe("/home");
+		});
+
+		test("handles meta.route as route object with path property", () => {
+			const meta = {
+				"root.profile": {
+					route: { path: "/profile", title: "Profile" },
+					view: { component: "Profile" },
+				},
+			};
+			const result = deriveRoute(meta);
+			expect(result).toBe("/profile");
+		});
+
+		test("normalizes various meta.route formats", () => {
+			const testCases = [
+				{ route: "/simple", expected: "/simple" },
+				{ route: { path: "/object" }, expected: "/object" },
+			];
+
+			testCases.forEach(({ route, expected }) => {
+				const meta = { "root.test": { route } };
+				expect(deriveRoute(meta)).toBe(expected);
+			});
+		});
+	});
+
+	describe("Precedence rules", () => {
+		test("prioritizes meta.route over meta.path within same state", () => {
+			const meta = {
+				"root.test": {
+					path: "/path-value",
+					route: "/route-value",
+				},
+			};
+			// When both exist on same state, meta.route takes precedence
+			const result = deriveRoute(meta);
+			expect(result).toBe("/route-value");
+		});
+	});
+
+	describe("Edge cases", () => {
+		test("returns null when no route or path in any state", () => {
+			const meta = {
+				root: {},
+				"root.loading": {
+					view: { component: "Loading" },
+				},
+			};
+			expect(deriveRoute(meta)).toBeNull();
+		});
+
+		test("handles empty meta object", () => {
+			const meta = {};
+			expect(deriveRoute(meta)).toBeNull();
+		});
+
+		test("handles null/undefined meta values", () => {
+			const meta = {
+				"root.a": null,
+				"root.b": undefined,
+				"root.c": {
+					route: "/valid",
+				},
+			};
+			expect(deriveRoute(meta)).toBe("/valid");
+		});
+
+		test("skips states without route metadata", () => {
+			const meta = {
+				root: { other: "data" },
+				"root.loading": { view: {} },
+				"root.error": { message: "error" },
+				"root.success": {
+					route: "/success",
+				},
+			};
+			expect(deriveRoute(meta)).toBe("/success");
+		});
+
+		test("handles meta with only view metadata (no routing)", () => {
+			const meta = {
+				"root.component": {
+					view: { component: "SomeComponent" },
+				},
+			};
+			expect(deriveRoute(meta)).toBeNull();
+		});
+	});
+
+	describe("Real-world scenarios", () => {
+		test("auth machine login state", () => {
+			const meta = {
+				root: {},
+				"root.public": {},
+				"root.public.login": {
+					route: "/",
+					view: { component: "Login" },
+				},
+			};
+			expect(deriveRoute(meta)).toBe("/");
+		});
+
+		test("auth machine authenticated home state", () => {
+			const meta = {
+				root: {},
+				"root.authenticated": {},
+				"root.authenticated.home": {
+					route: "/home",
+					view: { component: "Home" },
+				},
+			};
+			expect(deriveRoute(meta)).toBe("/home");
+		});
+
+		test("auth machine about state", () => {
+			const meta = {
+				root: {},
+				"root.public": {},
+				"root.public.about": {
+					route: "/about",
+					view: { component: "About" },
+				},
+			};
+			expect(deriveRoute(meta)).toBe("/about");
+		});
+
+		test("auth machine contact state", () => {
+			const meta = {
+				root: {},
+				"root.public": {},
+				"root.public.contact": {
+					route: "/contact",
+					view: { component: "Contact" },
+				},
+			};
+			expect(deriveRoute(meta)).toBe("/contact");
+		});
+	});
+});