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

package/.oxfmtrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@xmachines/shared/oxfmt"]
+}

package/.oxlintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@xmachines/shared/oxlint"]
+}

package/README.md

@@ -0,0 +1,177 @@
+# @xmachines/play-tanstack-react-router
+
+**TanStack React Router adapter for XMachines Play using the RouterBridge pattern.**
+
+## Overview
+
+`@xmachines/play-tanstack-react-router` connects a Play actor to TanStack Router through `TanStackReactRouterBridge`.
+
+The bridge extends `RouterBridgeBase` from `@xmachines/play-router`, so adapter behavior stays consistent across frameworks:
+
+- Actor route signal (`actor.currentRoute`) drives router navigation.
+- Router history events send `play.route` intents back to the actor.
+- Guarded state transitions remain actor-owned (Actor Authority).
+
+## Installation
+
+```bash
+npm install @tanstack/react-router react
+npm install @xmachines/play-tanstack-react-router @xmachines/play-router @xmachines/play-react
+```
+
+## Current Exports
+
+- `TanStackReactRouterBridge`
+- `RouteMap`, `createRouteMapFromTree`, `RouteMapping` (type)
+- `extractParams`, `extractQueryParams`
+- `PlayRouterProvider` + `PlayRouterProviderProps`
+- re-exports: `extractMachineRoutes`, `createRouteMap`, `RouterBridge`, `PlayRouteEvent`
+
+Peer dependencies:
+
+- `@tanstack/react-router` `^1.0.0`
+- `react` `^18 || ^19`
+
+## Browser Support
+
+This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching.
+
+Native support includes current Chrome, Firefox, and Safari 17.4+.
+For Node.js test environments or older browsers, install `urlpattern-polyfill`.
+
+```bash
+npm install urlpattern-polyfill
+```
+
+```ts
+if (!globalThis.URLPattern) {
+	await import("urlpattern-polyfill");
+}
+```
+
+## Quick Start
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { extractMachineRoutes } from "@xmachines/play-router";
+import {
+	TanStackReactRouterBridge,
+	createRouteMapFromTree,
+} from "@xmachines/play-tanstack-react-router";
+
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+const router = createRouter({ routeTree: tanstackRouteTree });
+
+const actor = definePlayer({ machine, catalog })();
+actor.start();
+
+const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+bridge.connect();
+
+// later
+bridge.disconnect();
+```
+
+### React convenience wrapper
+
+Use `PlayRouterProvider` when you want bridge lifecycle wiring in a component:
+
+```tsx
+import { PlayRenderer } from "@xmachines/play-react";
+
+<PlayRouterProvider
+	actor={actor}
+	router={router}
+	routeMap={routeMap}
+	renderer={(currentActor, currentRouter) => (
+		<PlayRenderer actor={currentActor} components={components} />
+	)}
+/>;
+```
+
+## API
+
+### `TanStackReactRouterBridge`
+
+Primary adapter class.
+
+```ts
+class TanStackReactRouterBridge implements RouterBridge {
+	constructor(
+		router: TanStackRouterLike,
+		actor: AbstractActor<AnyActorLogic> & Routable,
+		routeMap: RouteMap,
+	);
+	connect(): void;
+	disconnect(): void;
+}
+```
+
+### `RouteMap` and `createRouteMapFromTree`
+
+Map state IDs to URL paths and resolve URLs back to state IDs:
+
+```ts
+class RouteMap {
+	constructor(routes: Array<{ stateId: string; path: string }>);
+	getStateIdByPath(path: string): string | undefined;
+	getPathByStateId(stateId: string): string | undefined;
+}
+
+function createRouteMapFromTree(routeTree: RouteTree): RouteMap;
+```
+
+### `PlayRouterProvider`
+
+React wrapper around `TanStackReactRouterBridge`.
+
+```ts
+interface PlayRouterProviderProps {
+	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
+	router: TanStackRouterLike;
+	routeMap: RouteMap;
+	renderer: (
+		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
+		router: TanStackRouterLike,
+	) => ReactNode;
+}
+```
+
+### Utilities and re-exports
+
+- `extractParams`, `extractQueryParams`
+- `extractMachineRoutes`, `createRouteMap` (re-exported from `@xmachines/play-router`)
+- `RouterBridge`, `PlayRouteEvent` types
+
+## Examples
+
+- Multi-router integration guide: `docs/examples/multi-router-integration.md`
+- Routing patterns guide: `docs/examples/routing-patterns.md`
+
+## Architecture
+
+Bridge-first flow:
+
+1. `RouterBridgeBase.connect()` performs initial actor/router synchronization.
+2. Actor route updates call TanStack navigation (`router.navigate({ to })`).
+3. TanStack history updates are subscribed and translated to `play.route` events.
+4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
+
+This keeps routing infrastructure passive while preserving business-logic control.
+
+## Historical Note
+
+`SignalSyncedHistory` and `createPlayRouter` are legacy migration-era APIs and are not part of the current quick-start path. Use `TanStackReactRouterBridge` + `RouteMap` for new integrations.
+
+## Related Packages
+
+- [@xmachines/play-router](../play-router)
+- [@xmachines/play-xstate](../play-xstate)
+- [@xmachines/play-react](../play-react)
+
+## License
+
+MIT

package/dist/extract-params.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare function extractParams(pathname: string, pattern: string): Record<string, string>;
+/**
+ * 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 declare function extractQueryParams(search: string): Record<string, string>;
+//# sourceMappingURL=extract-params.d.ts.map

package/dist/extract-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-params.d.ts","sourceRoot":"","sources":["../src/extract-params.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsBvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOzE"}

package/dist/extract-params.js

@@ -0,0 +1,70 @@
+/**
+ * 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, pattern) {
+    // Reuse existing implementation from signal-synced-history.ts
+    // URLPattern-based extraction with :param syntax
+    const params = {};
+    // 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) {
+    const params = new URLSearchParams(search);
+    const result = {};
+    params.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+//# sourceMappingURL=extract-params.js.map

package/dist/extract-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-params.js","sourceRoot":"","sources":["../src/extract-params.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,OAAe;IAC9D,8DAA8D;IAC9D,iDAAiD;IACjD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,uDAAuD;IACvD,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAE9B,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACxD,IAAI,QAAQ,EAAE,CAAC;gBACd,MAAM,CAAC,SAAS,CAAC,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAClD,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAChD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @xmachines/play-tanstack-react-router
+ *
+ * TanStack Router adapter for XMachines Play architecture.
+ * Synchronizes browser URL with actor state through passive infrastructure.
+ *
+ * @packageDocumentation
+ */
+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";
+export { PlayRouterProvider, type PlayRouterProviderProps, type TanStackRouterInstance, } from "./play-router-provider.js";
+export { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+export type { RouteNavigateEvent } from "./types.js";
+export type { RouterBridge, PlayRouteEvent } from "@xmachines/play-router";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGtE,OAAO,EACN,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @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";
+// TanStack Router integration (React-only)
+export { PlayRouterProvider, } from "./play-router-provider.js";
+// Re-export shared utilities for convenience
+export { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mDAAmD;AACnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAIxE,2CAA2C;AAC3C,OAAO,EACN,kBAAkB,GAGlB,MAAM,2BAA2B,CAAC;AAEnC,6CAA6C;AAC7C,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/play-router-provider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { 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 declare function PlayRouterProvider({ actor, router, routeMap, renderer }: PlayRouterProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=play-router-provider.d.ts.map

package/dist/play-router-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"play-router-provider.d.ts","sourceRoot":"","sources":["../src/play-router-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,MAAM,sBAAsB,GAAG,qBAAqB,CAAC,OAAO,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhG,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1D,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,CACT,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,GAAG,QAAQ,EACzD,MAAM,EAAE,sBAAsB,KAC1B,SAAS,CAAC;CACf;AAED,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,uBAAuB,2CAQhG"}

package/dist/play-router-provider.js

@@ -0,0 +1,31 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 } from "react";
+import { TanStackReactRouterBridge } from "./tanstack-router-bridge.js";
+export function PlayRouterProvider({ actor, router, routeMap, renderer }) {
+    useEffect(() => {
+        const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+        bridge.connect();
+        return () => bridge.disconnect();
+    }, [actor, router, routeMap]);
+    return _jsx(_Fragment, { children: renderer(actor, router) });
+}
+//# sourceMappingURL=play-router-provider.js.map

package/dist/play-router-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"play-router-provider.js","sourceRoot":"","sources":["../src/play-router-provider.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,SAAS,EAAkB,MAAM,OAAO,CAAC;AAGlD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAexE,MAAM,UAAU,kBAAkB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAA2B;IAChG,SAAS,CAAC,GAAG,EAAE;QACd,MAAM,MAAM,GAAG,IAAI,yBAAyB,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QACtE,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;IAClC,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE9B,OAAO,4BAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GAAI,CAAC;AACvC,CAAC"}

package/dist/route-map.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 } 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 declare class RouteMap {
+    private stateIdToPath;
+    private pathToStateId;
+    private patterns;
+    /**
+     * Create RouteMap from route mappings
+     *
+     * @param routes - Array of state ID → path mappings
+     */
+    constructor(routes: RouteMapping[]);
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * 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 declare function createRouteMapFromTree(routeTree: RouteTree): RouteMap;
+//# sourceMappingURL=route-map.d.ts.map

package/dist/route-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,wBAAwB,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ;IACpB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAA4D;IAE5E;;;;OAIG;gBACS,MAAM,EAAE,YAAY,EAAE;IA0BlC;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAa7C;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAcrE"}

package/dist/route-map.js

@@ -0,0 +1,139 @@
+/**
+ * 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
+ */
+/**
+ * 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 {
+    stateIdToPath;
+    pathToStateId;
+    patterns;
+    /**
+     * Create RouteMap from route mappings
+     *
+     * @param routes - Array of state ID → path mappings
+     */
+    constructor(routes) {
+        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) {
+        // 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) {
+        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) {
+    const routes = [];
+    function traverse(node) {
+        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);
+}
+//# sourceMappingURL=route-map.js.map