@xmachines/play-router 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/find-route.js

@@ -0,0 +1,126 @@
+/**
+ * Check if a URL path matches a route pattern
+ *
+ * Handles parameter patterns including optional parameters (:param?).
+ * Used to match incoming URLs against route patterns with dynamic segments.
+ *
+ * Private — not exported from the package public API.
+ *
+ * @param path - URL path (e.g., '/settings', '/settings/billing')
+ * @param pattern - Route pattern (e.g., '/settings/:section?')
+ * @returns True if path matches pattern
+ *
+ * @example
+ * ```typescript
+ * matchesPattern('/settings', '/settings/:section?') // true
+ * matchesPattern('/settings/billing', '/settings/:section?') // true
+ * matchesPattern('/profile/123', '/profile/:userId') // true
+ * matchesPattern('/profile', '/profile/:userId') // false (required param missing)
+ * ```
+ */
+const matchesPattern = (path, pattern) => {
+    // No parameters - exact match required
+    if (!pattern.includes(":")) {
+        return path === pattern;
+    }
+    const patternSegments = pattern.split("/").filter(Boolean);
+    const pathSegments = path.split("/").filter(Boolean);
+    // Check each segment
+    for (let i = 0; i < patternSegments.length; i++) {
+        const patternSegment = patternSegments[i];
+        const pathSegment = pathSegments[i];
+        // Static segment - must match exactly
+        if (!patternSegment.startsWith(":")) {
+            if (patternSegment !== pathSegment) {
+                return false;
+            }
+            continue;
+        }
+        // Parameter segment
+        const isOptional = patternSegment.endsWith("?");
+        // Optional parameter - can be missing
+        if (isOptional && pathSegment === undefined) {
+            // Check if there are more path segments after this - if so, no match
+            if (i < pathSegments.length) {
+                return false;
+            }
+            continue;
+        }
+        // Required parameter - must exist
+        if (!isOptional && pathSegment === undefined) {
+            return false;
+        }
+    }
+    // If path has more segments than pattern, no match
+    // (unless all remaining pattern segments are optional - but we don't support that)
+    if (pathSegments.length > patternSegments.length) {
+        return false;
+    }
+    return true;
+};
+/**
+ * Find route node by state ID
+ *
+ * Looks up route node using the state's ID property. Used to get URL path
+ * from state ID for browser URL sync after play.route transitions.
+ *
+ * @param tree - Route tree from extractMachineRoutes
+ * @param id - State ID (e.g., 'dashboard', 'settings.profile')
+ * @returns Route node if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * const node = findRouteById(tree, 'dashboard');
+ * if (node) {
+ *   console.log(node.fullPath); // '/dashboard'
+ * }
+ * ```
+ */
+export const findRouteById = (tree, id) => {
+    return tree.byStateId.get(id);
+};
+/**
+ * Find route node by URL path
+ *
+ * Looks up route node using the URL path. Used to get state ID from browser
+ * URL for sending play.route events on navigation.
+ *
+ * When multiple states share the same path (e.g., root and a state both at "/"),
+ * prefers routable nodes (with meta.route) over non-routable nodes.
+ *
+ * Supports pattern matching for dynamic routes (e.g., '/settings/:section?').
+ *
+ * @param tree - Route tree from extractMachineRoutes
+ * @param path - URL path (e.g., '/dashboard', '/settings/profile')
+ * @returns Route node if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * const node = findRouteByPath(tree, '/dashboard');
+ * ```
+ */
+export const findRouteByPath = (tree, path) => {
+    // 1. Try exact match first (fast path for static routes)
+    const node = tree.byPath.get(path);
+    if (node?.routable) {
+        return node;
+    }
+    // 2. If exact match not found or non-routable, try pattern matching
+    // This handles:
+    // - Routes with parameters (e.g., '/settings/:section?')
+    // - Multiple states sharing same path (prefer routable)
+    for (const candidate of tree.byStateId.values()) {
+        if (!candidate.routable) {
+            continue; // Skip non-routable nodes
+        }
+        // Check if path matches this node's pattern
+        if (matchesPattern(path, candidate.fullPath)) {
+            return candidate;
+        }
+    }
+    // 3. Fallback: if we had a non-routable exact match, return it
+    return node;
+};
+//# sourceMappingURL=find-route.js.map

package/dist/find-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-route.js","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,cAAc,GAAG,CAAC,IAAY,EAAE,OAAe,EAAW,EAAE;IACjE,uCAAuC;IACvC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,KAAK,OAAO,CAAC;IACzB,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAErD,qBAAqB;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,cAAc,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAEpC,sCAAsC;QACtC,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,IAAI,cAAc,KAAK,WAAW,EAAE,CAAC;gBACpC,OAAO,KAAK,CAAC;YACd,CAAC;YACD,SAAS;QACV,CAAC;QAED,oBAAoB;QACpB,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAEhD,sCAAsC;QACtC,IAAI,UAAU,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC7C,qEAAqE;YACrE,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACd,CAAC;YACD,SAAS;QACV,CAAC;QAED,kCAAkC;QAClC,IAAI,CAAC,UAAU,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IAED,mDAAmD;IACnD,mFAAmF;IACnF,IAAI,YAAY,CAAC,MAAM,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAe,EAAE,EAAU,EAAyB,EAAE;IACnF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAe,EAAE,IAAY,EAAyB,EAAE;IACvF,yDAAyD;IACzD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,IAAI,EAAE,QAAQ,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,oEAAoE;IACpE,gBAAgB;IAChB,yDAAyD;IACzD,wDAAwD;IACxD,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;YACzB,SAAS,CAAC,0BAA0B;QACrC,CAAC;QAED,4CAA4C;QAC5C,IAAI,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,OAAO,SAAS,CAAC;QAClB,CAAC;IACF,CAAC;IAED,+DAA+D;IAC/D,OAAO,IAAI,CAAC;AACb,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,56 +1,17 @@
 export { RouterBridgeBase } from "./router-bridge-base.js";
-export { crawlMachine } from "./crawl-machine.js";
-export { extractRoute } from "./extract-route.js";
+export type { RouteWatcherHandle } from "./router-bridge-base.js";
+export { sanitizePathname } from "./router-sync.js";
 export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
 export { buildRouteTree } from "./build-tree.js";
 export { extractMachineRoutes } from "./extract-routes.js";
-export { getNavigableRoutes, getRoutableRoutes, routeExists } from "./query.js";
-export type { StateVisit, RouteInfo, RouteNode, RouteTree, PlayRouteEvent, RouterBridge, } from "./types.js";
+export { getNavigableRoutes, getRoutableRoutes, routeExists, getTransitionReachableRoutes, isRouteReachable, } from "./query.js";
+export { machineToGraph } from "./machine-to-graph.js";
+export type { MachineGraph } from "./machine-to-graph.js";
+export type { RouteInfo, RouteNode, RouteTree, RouteObject, RouteMetadata, PlayRouteEvent, RouterBridge, MachineNodeData, MachineEdgeData, } from "./types.js";
 export { createRouteMap, type RouteMap } from "./create-route-map.js";
-export { createBrowserHistory, type BrowserHistory } from "./create-browser-history.js";
+export { BaseRouteMap, type RouteMapping as BaseRouteMapping } from "./base-route-map.js";
+export { createBrowserHistory, type BrowserHistory, type BrowserWindow, } from "./create-browser-history.js";
 export { createRouter, type VanillaRouter } from "./create-router.js";
 export { connectRouter, type ConnectRouterOptions } from "./connect-router.js";
-import type { RouteTree, RouteNode } from "./types.js";
-/**
- * Find route node by state ID
- *
- * Looks up route node using the state's ID property. Used to get URL path
- * from state ID for browser URL sync after play.route transitions.
- *
- * @param tree - Route tree from extractMachineRoutes
- * @param id - State ID (e.g., 'dashboard', 'settings.profile')
- * @returns Route node if found, undefined otherwise
- *
- * @example
- * ```typescript
- * const tree = extractMachineRoutes(machine);
- * const node = findRouteById(tree, 'dashboard');
- * if (node) {
- *   console.log(node.fullPath); // '/dashboard'
- * }
- * ```
- */
-export declare const findRouteById: (tree: RouteTree, id: string) => RouteNode | undefined;
-/**
- * Find route node by URL path
- *
- * Looks up route node using the URL path. Used to get state ID from browser
- * URL for sending play.route events on navigation.
- *
- * When multiple states share the same path (e.g., root and a state both at "/"),
- * prefers routable nodes (with meta.route) over non-routable nodes.
- *
- * Supports pattern matching for dynamic routes (e.g., '/settings/:section?').
- *
- * @param tree - Route tree from extractMachineRoutes
- * @param path - URL path (e.g., '/dashboard', '/settings/profile')
- * @returns Route node if found, undefined otherwise
- *
- * @example
- * ```typescript
- * const tree = extractMachineRoutes(machine);
- * const node = findRouteByPath(tree, '/dashboard');
- * ```
- */
-export declare const findRouteByPath: (tree: RouteTree, path: string) => RouteNode | undefined;
+export { findRouteById, findRouteByPath } from "./find-route.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEhF,YAAY,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,cAAc,EACd,YAAY,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAGxF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAqEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,YAAY,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAKtE,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,IAAI,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG1F,OAAO,EACN,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,GAClB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG/E,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,141 +1,26 @@
 // RouterBridgeBase — public API for community adapters
 export { RouterBridgeBase } from "./router-bridge-base.js";
+// Router sync utilities — sanitizePathname is used by adapters that bypass syncActorFromRouter()
+export { sanitizePathname } from "./router-sync.js";
 // Route utilities (existing)
-export { crawlMachine } from "./crawl-machine.js";
-export { extractRoute } from "./extract-route.js";
 export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
 export { buildRouteTree } from "./build-tree.js";
 export { extractMachineRoutes } from "./extract-routes.js";
-export { getNavigableRoutes, getRoutableRoutes, routeExists } from "./query.js";
-// New: Route map for path → state ID resolution
+export { getNavigableRoutes, getRoutableRoutes, routeExists, getTransitionReachableRoutes, isRouteReachable, } from "./query.js";
+// Graph adapter — converts XState machines to @statelyai/graph Graph
+export { machineToGraph } from "./machine-to-graph.js";
+// Route map for path → state ID resolution (createRouteMap / RouteMap interface)
 export { createRouteMap } from "./create-route-map.js";
-// New: Browser history abstraction (aligned with TanStack Router)
-export { createBrowserHistory } from "./create-browser-history.js";
-// New: Vanilla router (framework-agnostic)
+// Shared bidirectional route mapping base class.
+// Re-exported as `BaseRouteMapping` (not `RouteMapping`) so adapter packages can
+// define their own local `RouteMapping` type without a name collision.
+export { BaseRouteMap } from "./base-route-map.js";
+// Browser history abstraction (aligned with TanStack Router)
+export { createBrowserHistory, } from "./create-browser-history.js";
+// Vanilla router (framework-agnostic)
 export { createRouter } from "./create-router.js";
-// New: Pure browser integration (low-level API)
+// Pure browser integration (low-level API)
 export { connectRouter } from "./connect-router.js";
-/**
- * Find route node by state ID
- *
- * Looks up route node using the state's ID property. Used to get URL path
- * from state ID for browser URL sync after play.route transitions.
- *
- * @param tree - Route tree from extractMachineRoutes
- * @param id - State ID (e.g., 'dashboard', 'settings.profile')
- * @returns Route node if found, undefined otherwise
- *
- * @example
- * ```typescript
- * const tree = extractMachineRoutes(machine);
- * const node = findRouteById(tree, 'dashboard');
- * if (node) {
- *   console.log(node.fullPath); // '/dashboard'
- * }
- * ```
- */
-export const findRouteById = (tree, id) => {
-    return tree.byStateId.get(id);
-};
-/**
- * Check if a URL path matches a route pattern
- *
- * Handles parameter patterns including optional parameters (:param?).
- * Used to match incoming URLs against route patterns with dynamic segments.
- *
- * @param path - URL path (e.g., '/settings', '/settings/billing')
- * @param pattern - Route pattern (e.g., '/settings/:section?')
- * @returns True if path matches pattern
- *
- * @example
- * ```typescript
- * matchesPattern('/settings', '/settings/:section?') // true
- * matchesPattern('/settings/billing', '/settings/:section?') // true
- * matchesPattern('/profile/123', '/profile/:userId') // true
- * matchesPattern('/profile', '/profile/:userId') // false (required param missing)
- * ```
- */
-const matchesPattern = (path, pattern) => {
-    // No parameters - exact match required
-    if (!pattern.includes(":")) {
-        return path === pattern;
-    }
-    const patternSegments = pattern.split("/").filter(Boolean);
-    const pathSegments = path.split("/").filter(Boolean);
-    // Check each segment
-    for (let i = 0; i < patternSegments.length; i++) {
-        const patternSegment = patternSegments[i];
-        const pathSegment = pathSegments[i];
-        // Static segment - must match exactly
-        if (!patternSegment.startsWith(":")) {
-            if (patternSegment !== pathSegment) {
-                return false;
-            }
-            continue;
-        }
-        // Parameter segment
-        const isOptional = patternSegment.endsWith("?");
-        // Optional parameter - can be missing
-        if (isOptional && pathSegment === undefined) {
-            // Check if there are more path segments after this - if so, no match
-            if (i < pathSegments.length) {
-                return false;
-            }
-            continue;
-        }
-        // Required parameter - must exist
-        if (!isOptional && pathSegment === undefined) {
-            return false;
-        }
-    }
-    // If path has more segments than pattern, no match
-    // (unless all remaining pattern segments are optional - but we don't support that)
-    if (pathSegments.length > patternSegments.length) {
-        return false;
-    }
-    return true;
-};
-/**
- * Find route node by URL path
- *
- * Looks up route node using the URL path. Used to get state ID from browser
- * URL for sending play.route events on navigation.
- *
- * When multiple states share the same path (e.g., root and a state both at "/"),
- * prefers routable nodes (with meta.route) over non-routable nodes.
- *
- * Supports pattern matching for dynamic routes (e.g., '/settings/:section?').
- *
- * @param tree - Route tree from extractMachineRoutes
- * @param path - URL path (e.g., '/dashboard', '/settings/profile')
- * @returns Route node if found, undefined otherwise
- *
- * @example
- * ```typescript
- * const tree = extractMachineRoutes(machine);
- * const node = findRouteByPath(tree, '/dashboard');
- * ```
- */
-export const findRouteByPath = (tree, path) => {
-    // 1. Try exact match first (fast path for static routes)
-    const node = tree.byPath.get(path);
-    if (node?.routable) {
-        return node;
-    }
-    // 2. If exact match not found or non-routable, try pattern matching
-    // This handles:
-    // - Routes with parameters (e.g., '/settings/:section?')
-    // - Multiple states sharing same path (prefer routable)
-    for (const candidate of tree.byStateId.values()) {
-        if (!candidate.routable) {
-            continue; // Skip non-routable nodes
-        }
-        // Check if path matches this node's pattern
-        if (matchesPattern(path, candidate.fullPath)) {
-            return candidate;
-        }
-    }
-    // 3. Fallback: if we had a non-routable exact match, return it
-    return node;
-};
+// Route lookup helpers — matchesPattern is private within find-route.ts
+export { findRouteById, findRouteByPath } from "./find-route.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,iGAAiG;AACjG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,6BAA6B;AAC7B,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACN,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,4BAA4B,EAC5B,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,qEAAqE;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAevD,iFAAiF;AACjF,OAAO,EAAE,cAAc,EAAiB,MAAM,uBAAuB,CAAC;AAEtE,iDAAiD;AACjD,iFAAiF;AACjF,uEAAuE;AACvE,OAAO,EAAE,YAAY,EAAyC,MAAM,qBAAqB,CAAC;AAE1F,6DAA6D;AAC7D,OAAO,EACN,oBAAoB,GAGpB,MAAM,6BAA6B,CAAC;AAErC,sCAAsC;AACtC,OAAO,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AAEtE,2CAA2C;AAC3C,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAE/E,wEAAwE;AACxE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/machine-to-graph.d.ts

@@ -0,0 +1,17 @@
+import type { AnyStateMachine } from "xstate";
+import { type Graph } from "@statelyai/graph";
+import type { MachineNodeData, MachineEdgeData } from "./types.js";
+/**
+ * Typed @statelyai/graph Graph representing a state machine.
+ * Provides hierarchy queries, traversal algorithms, and reachability checks.
+ *
+ * @example
+ * ```typescript
+ * import { getChildren, getSuccessors, hasPath } from "@statelyai/graph";
+ * const graph: MachineGraph = machineToGraph(machine);
+ * const children = getChildren(graph, "myMachine");
+ * ```
+ */
+export type MachineGraph = Graph<MachineNodeData, MachineEdgeData>;
+export declare const machineToGraph: (machine: AnyStateMachine) => MachineGraph;
+//# sourceMappingURL=machine-to-graph.d.ts.map

package/dist/machine-to-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-to-graph.d.ts","sourceRoot":"","sources":["../src/machine-to-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;AAqDnE,eAAO,MAAM,cAAc,GAAI,SAAS,eAAe,KAAG,YA2EzD,CAAC"}

package/dist/machine-to-graph.js

@@ -0,0 +1,115 @@
+import { toDirectedGraph } from "xstate/graph";
+import { createGraph } from "@statelyai/graph";
+/**
+ * Convert an XState v5 state machine to a typed @statelyai/graph Graph.
+ *
+ * The conversion pipeline is:
+ * `XState Machine → toDirectedGraph() → DirectedGraphNode hierarchy → createGraph() → Graph`
+ *
+ * The resulting graph captures:
+ * - **Hierarchy**: node parentId reflects XState compound/parallel nesting
+ * - **Edges**: all transitions with event types and optional guard types
+ * - **Metadata**: state type, meta object, and extracted route path
+ *
+ * @param machine - XState v5 state machine (any shape)
+ * @returns Typed directed graph with MachineNodeData on nodes and MachineEdgeData on edges
+ *
+ * @example
+ * Convert a simple machine and query its routes
+ * ```typescript
+ * import { createMachine } from "xstate";
+ * import { getChildren, getSuccessors } from "@statelyai/graph";
+ * import { machineToGraph } from "@xmachines/play-router";
+ *
+ * const machine = createMachine({
+ *   id: "app",
+ *   initial: "home",
+ *   states: {
+ *     home: { meta: { route: "/home" }, on: { GO_ABOUT: "about" } },
+ *     about: { meta: { route: "/about" } },
+ *   },
+ * });
+ *
+ * const graph = machineToGraph(machine);
+ * const children = getChildren(graph, "app"); // [home, about]
+ * const successors = getSuccessors(graph, "app.home"); // [about]
+ * ```
+ *
+ * @see {@link MachineNodeData} for node data shape
+ * @see {@link MachineEdgeData} for edge data shape
+ * @see https://github.com/statelyai/graph for @statelyai/graph API reference
+ */
+/**
+ * Set of valid XState state types for runtime validation.
+ * Guards against future XState changes or unexpected machine shapes.
+ */
+const VALID_STATE_TYPES = new Set([
+    "atomic",
+    "compound",
+    "parallel",
+    "final",
+    "history",
+]);
+export const machineToGraph = (machine) => {
+    const dg = toDirectedGraph(machine);
+    // Flatten DirectedGraphNode hierarchy into flat node/edge arrays
+    const nodes = [];
+    const edges = [];
+    let edgeCounter = 0;
+    const walk = (dgNode, parentId) => {
+        const sn = dgNode.stateNode;
+        const meta = sn.meta;
+        const metaRoute = meta?.["route"];
+        const route = typeof metaRoute === "string"
+            ? metaRoute
+            : typeof metaRoute === "object" && metaRoute !== null && "path" in metaRoute
+                ? metaRoute.path
+                : undefined;
+        // Runtime assertion: validate state type before casting
+        if (!VALID_STATE_TYPES.has(sn.type)) {
+            throw new Error(`Unknown XState state type "${sn.type}" on node "${sn.id}". ` +
+                `Expected one of: ${[...VALID_STATE_TYPES].join(", ")}.`);
+        }
+        const nodeData = {
+            stateId: sn.id,
+            type: sn.type,
+        };
+        if (meta !== undefined)
+            nodeData.meta = meta;
+        if (route !== undefined)
+            nodeData.route = route;
+        if (parentId !== undefined) {
+            nodes.push({ id: dgNode.id, parentId, data: nodeData });
+        }
+        else {
+            nodes.push({ id: dgNode.id, data: nodeData });
+        }
+        // Collect edges from THIS node (edges are on source node, not graph root)
+        for (const edge of dgNode.edges) {
+            const edgeData = {
+                eventType: edge.label.text,
+            };
+            if (edge.transition.guard) {
+                edgeData.guardType = String(edge.transition.guard);
+            }
+            edges.push({
+                id: `e${edgeCounter++}`,
+                sourceId: edge.source.id,
+                targetId: edge.target.id,
+                data: edgeData,
+            });
+        }
+        // Recurse into children with current node as parent
+        for (const child of dgNode.children) {
+            walk(child, dgNode.id);
+        }
+    };
+    walk(dg);
+    return createGraph({
+        type: "directed",
+        initialNodeId: dg.id,
+        nodes,
+        edges,
+    });
+};
+//# sourceMappingURL=machine-to-graph.js.map

package/dist/machine-to-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-to-graph.js","sourceRoot":"","sources":["../src/machine-to-graph.ts"],"names":[],"mappings":"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"}

package/dist/query.d.ts

@@ -1,4 +1,5 @@
-import type { RouteTree, RouteNode } from "./types.js";
+import type { Graph } from "@statelyai/graph";
+import type { RouteTree, RouteNode, MachineNodeData, MachineEdgeData } from "./types.js";
 /**
  * Get all routes navigable from given state
  *
@@ -49,4 +50,46 @@ export declare const getRoutableRoutes: (tree: RouteTree) => RouteNode[];
  * @returns true if path exists, false otherwise
  */
 export declare const routeExists: (tree: RouteTree, path: string) => boolean;
+/**
+ * Get routes reachable via transitions from current state
+ *
+ * Uses the @statelyai/graph successor algorithm to find all states
+ * directly reachable via transition edges from the given state,
+ * then filters to those with defined routes.
+ *
+ * @param graph - Machine graph from RouteTree.graph
+ * @param stateId - Current state ID (e.g., "test.home")
+ * @returns Array of route paths reachable via transitions
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * if (tree.graph) {
+ *   const reachable = getTransitionReachableRoutes(tree.graph, 'auth.loggedIn');
+ *   // ['/dashboard', '/settings'] — routes reachable via transitions
+ * }
+ * ```
+ */
+export declare const getTransitionReachableRoutes: (graph: Graph<MachineNodeData, MachineEdgeData>, stateId: string) => string[];
+/**
+ * Check if a route is reachable from current state via transitions
+ *
+ * Uses @statelyai/graph path-finding to determine if there exists
+ * a chain of transition edges from the source state to the target state.
+ *
+ * @param graph - Machine graph from RouteTree.graph
+ * @param fromStateId - Source state ID
+ * @param toStateId - Target state ID
+ * @returns true if a transition path exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * if (tree.graph) {
+ *   const canReach = isRouteReachable(tree.graph, 'auth.login', 'auth.dashboard');
+ *   // true if login → dashboard transition path exists
+ * }
+ * ```
+ */
+export declare const isRouteReachable: (graph: Graph<MachineNodeData, MachineEdgeData>, fromStateId: string, toStateId: string) => boolean;
 //# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,EAAE,SAAS,MAAM,KAAG,SAAS,EAO9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,SAAS,KAAG,SAAS,EAW5D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,OAE3D,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,EAAE,SAAS,MAAM,KAAG,SAAS,EAsB9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,SAAS,KAAG,SAAS,EAW5D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,OAE3D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,EAC9C,SAAS,MAAM,KACb,MAAM,EAWR,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,GAC5B,OAAO,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,EAC9C,aAAa,MAAM,EACnB,WAAW,MAAM,KACf,OASF,CAAC"}