@xmachines/play-router 1.0.0-beta.9 → 1.0.0

package/dist/extract-routes.js

@@ -1,61 +1,83 @@
-import { crawlMachine } from "./crawl-machine.js";
-import { extractRoute } from "./extract-route.js";
-import { detectDuplicateRoutes } from "./validate-routes.js";
+import { machineToGraph } from "./machine-to-graph.js";
+import { validateRouteFormat, validateStateExists } from "./validate-routes.js";
 import { buildRouteTree } from "./build-tree.js";
 /**
- * Extract complete route tree from state machine graph
- *
- * Crawls machine starting from root, visits all state nodes (including nested
- * and parallel), extracts meta.route metadata, validates route references,
- * and builds hierarchical tree.
+ * Build statePath for a graph node by walking the parentId chain.
  *
- * @param machine - XState v5 state machine
- * @returns Route tree with root, byStateId map, and byPath map
- * @throws {Error} If route references non-existent state
- * @throws {Error} If route path is malformed (doesn't start with /)
- * @throws {Error} If parallel states define conflicting routes
+ * Produces an array of stateId segments from root to this node (excluding root),
+ * matching the format expected by buildRouteTree's parent lookup.
  *
- * @example
- * ```typescript
- * import { createMachine } from 'xstate';
- * import { extractMachineRoutes } from '@xmachines/play-router';
+ * @param graphNode - The node to build a path for
+ * @param graphNodeMap - Map from node id to GraphNode for O(1) parent lookup
+ * @returns Array of stateId segments (e.g. ["dashboard", "overview"])
+ */
+const buildStatePath = (graphNode, graphNodeMap) => {
+    const path = [];
+    let current = graphNode;
+    while (current && current.parentId !== undefined && current.parentId !== null) {
+        path.unshift(current.data.stateId);
+        current = graphNodeMap.get(current.parentId);
+    }
+    return path;
+};
+/**
+ * Extract route info from a graph node's MachineNodeData.
+ * Returns null if the node has no route (not routable).
+ */
+const extractRouteFromNode = (graphNode, stateIds, graphNodeMap) => {
+    const { stateId, route, meta } = graphNode.data;
+    // Node has no route — not routable
+    if (!route)
+        return null;
+    // Validate format (must start with /)
+    validateRouteFormat(route, stateId);
+    // Validate state exists in graph (redundant but guards against corruption)
+    validateStateExists(stateId, stateIds);
+    // Build statePath from parentId chain (works for both explicit IDs and auto-generated)
+    const statePath = buildStatePath(graphNode, graphNodeMap);
+    const pattern = route.includes(":") ? route : undefined;
+    // Reconstruct original metadata shape from graph data
+    const metadata = meta && typeof meta === "object" && "route" in meta
+        ? meta["route"]
+        : route;
+    const result = {
+        stateId,
+        statePath,
+        routePath: route,
+        isAbsolute: route.startsWith("/"),
+        routable: true,
+        metadata,
+    };
+    if (pattern)
+        result.pattern = pattern;
+    return result;
+};
+/**
+ * Extract complete route tree from state machine graph
  *
- * const machine = createMachine({
- *   initial: 'home',
- *   states: {
- *     home: { id: 'home', meta: { route: '/' } },
- *     dashboard: {
- *       id: 'dashboard',
- *       meta: { route: '/dashboard' },
- *       initial: 'overview',
- *       states: {
- *         overview: { id: 'overview', meta: { route: '/overview' } }
- *       }
- *     }
- *   }
- * });
+ * Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
+ * then walks graph nodes to extract route metadata, validate route references,
+ * and build a hierarchical RouteTree. The graph is attached to the returned
+ * RouteTree for downstream transition-aware queries.
  *
- * const tree = extractMachineRoutes(machine);
- * console.log(tree.byPath.get('/dashboard/overview'));
- * ```
+ * @param machine - XState v5 state machine
+ * @returns Route tree with root, byStateId map, byPath map, and graph
  */
 export const extractMachineRoutes = (machine) => {
-    // 1. Crawl machine graph to discover all states
-    const visits = crawlMachine(machine);
-    // 2. Build state map for validation
-    const stateMap = new Map();
-    for (const visit of visits) {
-        if (visit.node.id) {
-            stateMap.set(visit.node.id, visit.node);
-        }
-    }
-    // 3. Extract routes with validation
-    const routes = visits
-        .map((visit) => extractRoute(visit.node, visit.path, stateMap))
-        .filter((route) => route !== null);
-    // 4. Detect duplicate routes
-    detectDuplicateRoutes(routes);
-    // 5. Build hierarchical tree
-    return buildRouteTree(routes);
+    // 1. Convert machine to graph
+    const graph = machineToGraph(machine);
+    // 2. Build state ID set for validation and node map for O(1) parent lookup
+    const stateIds = new Set(graph.nodes.map((n) => n.data.stateId));
+    const graphNodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    // 3. Extract routes from graph nodes
+    const routes = graph.nodes
+        .map((node) => extractRouteFromNode(node, stateIds, graphNodeMap))
+        .filter((r) => r !== null);
+    // 4. Build hierarchical tree and attach graph.
+    // Duplicate-route detection happens inside buildRouteTree, AFTER relative
+    // routes are resolved to full paths — raw route strings are not comparable
+    // (two relative "settings" routes under different parents are distinct).
+    const tree = buildRouteTree(routes);
+    return { ...tree, graph };
 };
 //# sourceMappingURL=extract-routes.js.map

package/dist/extract-routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract-routes.js","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAa,EAAE;IAC3E,gDAAgD;IAChD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAErC,oCAAoC;IACpC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACnB,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED,oCAAoC;IACpC,MAAM,MAAM,GAAG,MAAM;SACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;SAC9D,MAAM,CAAC,CAAC,KAAK,EAAsC,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;IAExE,6BAA6B;IAC7B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAE9B,6BAA6B;IAC7B,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC,CAAC"}
+{"version":3,"file":"extract-routes.js","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"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"}

package/dist/find-route.d.ts

@@ -0,0 +1,44 @@
+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;
+//# sourceMappingURL=find-route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"find-route.d.ts","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqCvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}

package/dist/find-route.js

@@ -0,0 +1,103 @@
+import { getURLPatternCtor, getCompiledPattern } from "./url-pattern-utils.js";
+import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.js";
+/**
+ * Check if a URL path matches a route pattern using URLPattern.
+ *
+ * For static patterns (no `:param`) falls back to a direct equality check so
+ * URLPattern is never required for polyfill-free environments that only use
+ * static routes.
+ *
+ * Uses the shared module-level compiled-pattern cache (`getCompiledPattern`)
+ * so repeated lookups never recompile the same pattern, and hyphenated param
+ * names (`:cat-id`) are normalized exactly as `RouteMap` does — the same single
+ * matching engine underneath.
+ *
+ * Throws `URLPatternUnavailableError` when a parameterised pattern is tested
+ * and URLPattern is not available on `globalThis`.
+ * Throws `InvalidRoutePatternError` when URLPattern cannot compile the pattern.
+ *
+ * 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
+ */
+function matchesPattern(path, pattern) {
+    if (!pattern.includes(":"))
+        return path === pattern;
+    const Ctor = getURLPatternCtor();
+    if (!Ctor)
+        throw new URLPatternUnavailableError();
+    try {
+        return getCompiledPattern(pattern, Ctor).test({ pathname: path });
+    }
+    catch (err) {
+        throw new InvalidRoutePatternError(pattern, { cause: err });
+    }
+}
+/**
+ * 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":"AACA,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,OAAe;IACpD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,KAAK,OAAO,CAAC;IACpD,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,0BAA0B,EAAE,CAAC;IAClD,IAAI,CAAC;QACJ,OAAO,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,wBAAwB,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;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,57 +1,18 @@
 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, buildPlayRouteEvent, extractQuery, extractRouteParams, } from "./router-sync.js";
+export type { RouteMatch, BuildPlayRouteEventOptions } from "./router-sync.js";
 export { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
+export type { ResolvedRoutePath } 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, RouteObject, RouteMetadata, PlayRouteEvent, RouterBridge, } from "./types.js";
-export { createRouteMap, type RouteMap } from "./create-route-map.js";
-export { BaseRouteMap, type RouteMapping as BaseRouteMapping } from "./base-route-map.js";
-export { createBrowserHistory, type BrowserHistory } 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 { 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, RoutableActor, PlayActor, RouterBridge, MachineNodeData, MachineEdgeData, WindowLike, LocationLike, } from "./types.js";
+export { RouteMap, type RouteMapping, type RouteMapping as BaseRouteMapping, } from "./base-route-map.js";
+export { createRouteMap } from "./create-route-map.js";
+export type { RouteMapOptions } from "./create-route-map.js";
+export { createRouteMapFromTree } from "./create-route-map-from-tree.js";
+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,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,GACZ,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,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,EACN,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,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,aAAa,EACb,SAAS,EACT,YAAY,EACZ,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,GACZ,MAAM,YAAY,CAAC;AAIpB,OAAO,EACN,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,YAAY,IAAI,gBAAgB,GACrC,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,145 +1,21 @@
 // RouterBridgeBase — public API for community adapters
 export { RouterBridgeBase } from "./router-bridge-base.js";
+// Router sync utilities — used by play-dom-router and adapters that bypass syncActorFromRouter()
+export { sanitizePathname, buildPlayRouteEvent, extractQuery, extractRouteParams, } 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";
-// Route map for path → state ID resolution (createRouteMap / RouteMap interface)
-export { createRouteMap } from "./create-route-map.js";
+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";
 // 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";
-// 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;
-};
+// RouteMapping is exported directly; BaseRouteMapping kept as alias for compatibility.
+export { RouteMap, } from "./base-route-map.js";
+// Factories: create a RouteMap from a machine or a route tree.
+// All RouterBridgeBase adapters use these instead of rolling their own factories.
+export { createRouteMap } from "./create-route-map.js";
+export { createRouteMapFromTree } from "./create-route-map-from-tree.js";
+// 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,EACN,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,6BAA6B;AAC7B,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,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;AAmBvD,iDAAiD;AACjD,uFAAuF;AACvF,OAAO,EACN,QAAQ,GAGR,MAAM,qBAAqB,CAAC;AAE7B,+DAA+D;AAC/D,kFAAkF;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,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;AAGnE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;AAqDnE,eAAO,MAAM,cAAc,GAAI,SAAS,eAAe,KAAG,YAwEzD,CAAC"}