@xmachines/docs 1.0.0-beta.17 → 1.0.0-beta.19

package/api/@xmachines/play-router/README.md

@@ -4,11 +4,11 @@
 
 **Route tree extraction from XState v5 state machines with routing patterns**
 
-BFS graph crawling and bidirectional route lookup enabling Actor Authority over navigation.
+Graph-based route extraction and bidirectional lookup enabling Actor Authority over navigation.
 
 ## Overview
 
-`@xmachines/play-router` extracts route trees from XState state machines by crawling the state graph using breadth-first traversal. It extracts `meta.route` paths from state machines and builds hierarchical route trees with bidirectional state ID ↔ path mapping.
+`@xmachines/play-router` extracts route trees from XState state machines using `@statelyai/graph` — a typed, JSON-serializable graph library. It converts machines to a directed `Graph` with hierarchy, transition edges, and route metadata, then builds hierarchical `RouteTree` structures with bidirectional state ID ↔ path mapping.
 
 It also exports `RouterBridgeBase`, the shared base class used by framework adapters to implement `RouterBridge` with consistent actor↔router synchronization behavior.
 
@@ -16,7 +16,7 @@ It also exports `RouterBridgeBase`, the shared base class used by framework adap
 
 The low-level `connectRouter()` path now uses the same router-to-actor event builder and route-map match helper as `RouterBridgeBase`, so pathname sanitization, state-id normalization, param extraction, and query extraction stay aligned across vanilla and framework adapters.
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+Per [Play RFC](../../_media/play.md), this package implements:
 
 - **Actor Authority (INV-01):** Routes derive from machine definitions, not external configuration
 
@@ -50,13 +50,13 @@ Install the polyfill:
 npm install urlpattern-polyfill
 ```
 
-`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — it is the consumer's responsibility to load it when needed.
+`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — consumers must install and load it when their runtime lacks native URLPattern support (Node.js < 24, older browsers).
 
 ## Quick Start
 
 ```typescript
 import { createMachine } from "xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
 
 // Route pattern (recommended)
 const machine = createMachine({
@@ -88,11 +88,11 @@ const machine = createMachine({
 const tree = extractMachineRoutes(machine);
 
 // Bidirectional lookup
-console.log(tree.byPath.get("/dashboard/overview")); // RouteNode
-console.log(tree.byId.get("overview")); // RouteNode
+console.log(findRouteByPath(tree, "/overview")); // RouteNode
+console.log(tree.byStateId.get("overview")); // RouteNode
 
 // Pattern matching for dynamic routes
-const settingsRoute = tree.byPath.get("/settings/profile");
+const settingsRoute = findRouteByPath(tree, "/settings/profile");
 console.log(settingsRoute?.id); // "settings"
 ```
 
@@ -210,9 +210,10 @@ const tree = extractMachineRoutes(machine: AnyStateMachine): RouteTree;
 
 **Returns:** `RouteTree` with:
 
-- `routes: RouteNode[]` - Array of route nodes
-- `byPath: Map<string, RouteNode>` - URL path → route node
-- `byId: Map<string, RouteNode>` - State ID → route node
+- `byPath: Map<string, RouteNode>` — URL path → route node
+- `byStateId: Map<string, RouteNode>` — State ID → route node
+- `root: RouteNode` — synthetic root node
+- `graph: MachineGraph` — `@statelyai/graph` Graph for hierarchy queries, reachability checks, and transition-aware navigation
 
 **Throws:** Error if routes are invalid (malformed paths, missing state IDs, duplicates)
 
@@ -224,47 +225,77 @@ import { extractMachineRoutes } from "@xmachines/play-router";
 const tree = extractMachineRoutes(authMachine);
 
 // Query routes
-const loginRoute = tree.byId.get("login");
+const loginRoute = tree.byStateId.get("login");
 console.log(loginRoute?.path); // "/login"
 
 const dashboardRoute = tree.byPath.get("/dashboard");
 console.log(dashboardRoute?.id); // "dashboard"
 ```
 
-### crawlMachine()
+### machineToGraph()
 
-Low-level BFS traversal of state machine graph:
+Converts an XState v5 machine to a typed `@statelyai/graph` `Graph`:
 
 ```typescript
-const visits = crawlMachine(machine: AnyStateMachine): StateVisit[];
-```
+import { machineToGraph } from "@xmachines/play-router";
+import { getChildren, getSuccessors, hasPath } from "@statelyai/graph";
 
-**Returns:** Array of state visits in breadth-first order with:
+const graph = machineToGraph(machine);
 
-- `path: string[]` - State path (e.g., ["dashboard", "settings"])
-- `parent: StateNode | null` - Parent state node
-- `node: StateNode` - Current state node
+// Hierarchy queries
+const children = getChildren(graph, "myMachine");
+const successors = getSuccessors(graph, "myMachine.home"); // transition-reachable states
 
-**Example:**
+// Reachability
+const reachable = hasPath(graph, "myMachine.home", "myMachine.dashboard");
+```
+
+The graph is also available on any `RouteTree` returned by `extractMachineRoutes()`:
 
 ```typescript
-import { crawlMachine } from "@xmachines/play-router";
+const tree = extractMachineRoutes(machine);
 
-const visits = crawlMachine(machine);
-visits.forEach((visit) => {
-	console.log("State:", visit.path.join("."));
-	console.log("Parent:", visit.parent?.id ?? "root");
-});
+// Use @statelyai/graph algorithms directly on the graph
+const successors = getSuccessors(tree.graph!, "myMachine.home");
 ```
 
+**Node data** (`MachineNodeData`):
+
+- `stateId: string` — XState state ID (e.g., `"myMachine.dashboard.overview"`)
+- `type` — `"atomic" | "compound" | "parallel" | "final" | "history"`
+- `meta?: Record<string, unknown>` — original state meta object
+- `route?: string` — extracted route path from `meta.route`
+
+**Edge data** (`MachineEdgeData`):
+
+- `eventType: string` — event type triggering this transition
+- `guardType?: string` — guard name/description (if transition is guarded)
+
 ### Query Utilities
 
 ```typescript
-// Get child routes from state
-const children = getNavigableRoutes(tree, "dashboard");
+import {
+	getNavigableRoutes,
+	getRoutableRoutes,
+	routeExists,
+	getTransitionReachableRoutes,
+	isRouteReachable,
+} from "@xmachines/play-router";
+
+// Child routes (hierarchical + transition-reachable)
+const navigable = getNavigableRoutes(tree, "dashboard");
+
+// All routable routes as flat array
+const allRoutes = getRoutableRoutes(tree);
 
-// Check if route exists
+// Check path exists
 const exists = routeExists(tree, "/profile/:userId");
+
+// Transition-aware: which state IDs are reachable via transitions?
+const reachableIds = getTransitionReachableRoutes(tree.graph!, "myMachine.home");
+
+// Is there any path from state A to state B via transitions?
+const canReach = isRouteReachable(tree.graph!, "myMachine.home", "myMachine.dashboard");
 ```
 
 ## Examples
@@ -272,7 +303,7 @@ const exists = routeExists(tree, "/profile/:userId");
 ### Route Detection
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
 import { createMachine } from "xstate";
 
 const machine = createMachine({
@@ -296,10 +327,10 @@ const machine = createMachine({
 const tree = extractMachineRoutes(machine);
 
 // Bidirectional mapping
-const profileById = tree.byId.get("profile");
+const profileById = tree.byStateId.get("profile");
 console.log(profileById?.path); // "/profile/:userId"
 
-const profileByPath = tree.byPath.get("/profile/user123");
+const profileByPath = findRouteByPath(tree, "/profile/user123");
 console.log(profileByPath?.id); // "profile"
 ```
 
@@ -343,14 +374,14 @@ const dashboardChildren = getNavigableRoutes(tree, "dashboard");
 console.log(dashboardChildren.map((r) => r.id)); // ["overview", "analytics"]
 
 // Route inheritance
-const analyticsRoute = tree.byId.get("analytics");
-console.log(analyticsRoute?.path); // "/dashboard/analytics" (inherited parent path)
+const analyticsRoute = tree.byStateId.get("analytics");
+console.log(analyticsRoute?.fullPath); // "/analytics" (absolute route)
 ```
 
 ### Pattern Matching
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
 
 const machine = createMachine({
 	states: {
@@ -368,13 +399,13 @@ const machine = createMachine({
 const tree = extractMachineRoutes(machine);
 
 // Pattern matching for actual URLs
-const userRoute = tree.byPath.get("/user/user123");
+const userRoute = findRouteByPath(tree, "/user/user123");
 console.log(userRoute?.id); // "user"
 
-const settingsDefault = tree.byPath.get("/settings");
+const settingsDefault = findRouteByPath(tree, "/settings");
 console.log(settingsDefault?.id); // "settings" (optional param)
 
-const settingsProfile = tree.byPath.get("/settings/profile");
+const settingsProfile = findRouteByPath(tree, "/settings/profile");
 console.log(settingsProfile?.id); // "settings" (with param)
 ```
 
@@ -420,7 +451,7 @@ states: {
 			},
 			relative: {
 				id: "relative",
-				meta: { route: "relative", view: { component: "Relative" } }, // No leading / → inherits parent
+				meta: { route: "relative", view: { component: "Relative" } }, // No leading / → inherits parent path prefix
 				// Final path: "/parent/relative"
 			},
 		},
@@ -441,6 +472,25 @@ meta: {
 
 **Parameter substitution:** Values extracted from context or event params (handled by play-xstate adapter).
 
+## Security Utilities
+
+### `sanitizePathname()`
+
+Normalize a raw pathname before route-map lookup. Used internally by `RouterBridgeBase.syncActorFromRouter()` and available to adapters that bypass the base class:
+
+```typescript
+import { sanitizePathname } from "@xmachines/play-router";
+
+// In a custom adapter's route-watch callback:
+const clean = sanitizePathname(rawPath);
+if (clean === null) return; // Reject malformed/oversized paths (> 2048 chars)
+// Proceed with clean normalized path
+```
+
+Returns `null` for paths exceeding 2048 characters. Strips query fragments, hash fragments, and collapses duplicate slashes.
+
+---
+
 ## Error Handling
 
 All runtime errors thrown by this package extend `PlayError` from `@xmachines/play` and
@@ -483,15 +533,17 @@ try {
 This package enables **Actor Authority (INV-01)**:
 
 1. **Routes derive from machine:** Business logic defines routes in state machine, not external config
-2. **BFS traversal:** Systematic state discovery ensures all nested states visited
-3. **Bidirectional mapping:** Fast lookup by path (browser URL) or by ID (state machine)
-4. **Build-time validation:** Invalid routes throw errors during extraction, not runtime
+2. **Graph-based extraction:** `machineToGraph()` converts machines to typed `@statelyai/graph` `Graph` objects with hierarchy, transition edges, and route metadata
+3. **Bidirectional mapping:** Fast lookup by path (browser URL) or by state ID (state machine)
+4. **Transition-aware queries:** `getTransitionReachableRoutes()` and `isRouteReachable()` use graph algorithms for navigation reachability
+5. **Build-time validation:** Invalid routes throw errors during extraction, not runtime
 
 **Enhancements:**
 
-- `meta.route` detection via state metadata
+- `meta.route` detection via state metadata — extracted into typed graph node data
 - Pattern matching for dynamic routes (`:param` and `:param?`)
 - State ID ↔ path bidirectional maps for `play.route` events
+- `@statelyai/graph` integration — hierarchy queries, reachability checks, transition traversal
 
 ## Related Packages
 
@@ -518,6 +570,8 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [BrowserHistory](interfaces/BrowserHistory.md)
 - [BrowserWindow](interfaces/BrowserWindow.md)
 - [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [MachineEdgeData](interfaces/MachineEdgeData.md)
+- [MachineNodeData](interfaces/MachineNodeData.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RouteInfo](interfaces/RouteInfo.md)
 - [RouteMap](interfaces/RouteMap.md)
@@ -526,28 +580,30 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [RouterBridge](interfaces/RouterBridge.md)
 - [RouteTree](interfaces/RouteTree.md)
 - [RouteWatcherHandle](interfaces/RouteWatcherHandle.md)
-- [StateVisit](interfaces/StateVisit.md)
 - [VanillaRouter](interfaces/VanillaRouter.md)
 
 ## Type Aliases
 
+- [MachineGraph](type-aliases/MachineGraph.md)
 - [RouteMetadata](type-aliases/RouteMetadata.md)
 
 ## Functions
 
 - [buildRouteTree](functions/buildRouteTree.md)
 - [connectRouter](functions/connectRouter.md)
-- [crawlMachine](functions/crawlMachine.md)
 - [createBrowserHistory](functions/createBrowserHistory.md)
 - [createRouteMap](functions/createRouteMap.md)
 - [createRouter](functions/createRouter.md)
 - [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
 - [extractMachineRoutes](functions/extractMachineRoutes.md)
-- [extractRoute](functions/extractRoute.md)
 - [findRouteById](functions/findRouteById.md)
 - [findRouteByPath](functions/findRouteByPath.md)
 - [getNavigableRoutes](functions/getNavigableRoutes.md)
 - [getRoutableRoutes](functions/getRoutableRoutes.md)
+- [getTransitionReachableRoutes](functions/getTransitionReachableRoutes.md)
+- [isRouteReachable](functions/isRouteReachable.md)
+- [machineToGraph](functions/machineToGraph.md)
 - [routeExists](functions/routeExists.md)
+- [sanitizePathname](functions/sanitizePathname.md)
 - [validateRouteFormat](functions/validateRouteFormat.md)
 - [validateStateExists](functions/validateStateExists.md)

package/api/@xmachines/play-router/classes/BaseRouteMap.md

@@ -2,7 +2,7 @@
 
 # Class: BaseRouteMap
 
-Defined in: [base-route-map.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L106)
+Defined in: [base-route-map.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/base-route-map.ts#L106)
 
 Shared bidirectional route map base class.
 
@@ -57,7 +57,7 @@ map.getPathByStateId("missing"); // null
 new BaseRouteMap(mappings): BaseRouteMap;
 ```
 
-Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -83,7 +83,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L210)
+Defined in: [base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/base-route-map.ts#L210)
 
 Look up the path pattern registered for a state ID.
 
@@ -114,7 +114,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L175)
+Defined in: [base-route-map.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/base-route-map.ts#L175)
 
 Resolve a URL path to its mapped state ID.
 

package/api/@xmachines/play-router/classes/RouterBridgeBase.md

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L82)
+Defined in: [router-bridge-base.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L82)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -30,7 +30,7 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L96)
+Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L96)
 
 #### Parameters
 
@@ -49,15 +49,15 @@ Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-j
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Defined in                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [router-bridge-base.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L97)   |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L85)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L84)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L87)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L86)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L98)   |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L100) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L99)   |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [router-bridge-base.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L97)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L85)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L84)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L98)   |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L88)   |
 
 ## Methods
 
@@ -67,7 +67,7 @@ Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-j
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L116)
+Defined in: [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L116)
 
 Connect the router bridge to the Actor.
 
@@ -90,7 +90,7 @@ starts watching router changes (framework-specific).
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L184)
+Defined in: [router-bridge-base.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L184)
 
 Disconnect the router bridge from the Actor.
 
@@ -112,7 +112,7 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L283)
+Defined in: [router-bridge-base.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L283)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -142,7 +142,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L310)
+Defined in: [router-bridge-base.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L310)
 
 Extract query parameters from URL search string.
 
@@ -166,7 +166,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L357)
+Defined in: [router-bridge-base.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L357)
 
 Return the router's current pathname at connect() time.
 
@@ -198,7 +198,7 @@ bridges that have not yet implemented this hook.
 abstract protected navigateRouter(path): void;
 ```
 
-Defined in: [router-bridge-base.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L322)
+Defined in: [router-bridge-base.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L322)
 
 Navigate the framework router to the given path.
 
@@ -223,7 +223,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [router-bridge-base.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L231)
+Defined in: [router-bridge-base.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L231)
 
 Sync actor state when router location changes.
 
@@ -249,7 +249,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [router-bridge-base.ts:211](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L211)
+Defined in: [router-bridge-base.ts:211](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L211)
 
 Sync router location when actor route signal changes.
 
@@ -274,7 +274,7 @@ Prevents circular updates via isProcessingNavigation flag.
 abstract protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:337](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L337)
+Defined in: [router-bridge-base.ts:337](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L337)
 
 Stop watching for router location changes.
 
@@ -292,7 +292,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 abstract protected watchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L330)
+Defined in: [router-bridge-base.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/router-bridge-base.ts#L330)
 
 Start watching for router location changes.
 

package/api/@xmachines/play-router/functions/buildRouteTree.md

@@ -6,7 +6,7 @@
 function buildRouteTree(routes): RouteTree;
 ```
 
-Defined in: [build-tree.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/build-tree.ts#L13)
+Defined in: [build-tree.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/build-tree.ts#L13)
 
 Build hierarchical route tree from flat route list
 

package/api/@xmachines/play-router/functions/connectRouter.md

@@ -6,7 +6,7 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [connect-router.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/connect-router.ts#L59)
+Defined in: [connect-router.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/connect-router.ts#L59)
 
 Connect vanilla router to actor (pure browser integration).
 

package/api/@xmachines/play-router/functions/createBrowserHistory.md

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [create-browser-history.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L115)
+Defined in: [create-browser-history.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/create-browser-history.ts#L115)
 
 Create browser history that wraps window.history
 

package/api/@xmachines/play-router/functions/createRouteMap.md

@@ -6,7 +6,7 @@
 function createRouteMap(routeTree): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-route-map.ts#L121)
+Defined in: [create-route-map.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/create-route-map.ts#L121)
 
 Create a RouteMap from a RouteTree for efficient path lookups.
 

package/api/@xmachines/play-router/functions/createRouter.md

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [create-router.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-router.ts#L73)
+Defined in: [create-router.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/create-router.ts#L73)
 
 Create vanilla router for framework-agnostic routing.
 

package/api/@xmachines/play-router/functions/detectDuplicateRoutes.md

@@ -6,7 +6,7 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/validate-routes.ts#L51)
+Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/validate-routes.ts#L51)
 
 Detect duplicate route paths
 

package/api/@xmachines/play-router/functions/extractMachineRoutes.md

@@ -6,13 +6,14 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [extract-routes.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/extract-routes.ts#L45)
+Defined in: [extract-routes.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.19/packages/play-router/src/extract-routes.ts#L93)
 
 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.
+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.
 
 ## Parameters
 
@@ -24,41 +25,4 @@ and builds hierarchical tree.
 
 [`RouteTree`](../interfaces/RouteTree.md)
 
-Route tree with root, byStateId map, and byPath map
-
-## Throws
-
-If route references non-existent state
-
-## Throws
-
-If route path is malformed (doesn't start with /)
-
-## Throws
-
-If parallel states define conflicting routes
-
-## Example
-
-```typescript
-import { createMachine } from "xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
-
-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" } },
-			},
-		},
-	},
-});
-
-const tree = extractMachineRoutes(machine);
-console.log(tree.byPath.get("/dashboard/overview"));
-```
+Route tree with root, byStateId map, byPath map, and graph