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

package/README.md

@@ -2,17 +2,19 @@
 
 **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.
 
 `RouterBridgeBase` is the policy point; framework adapters are thin ports that implement only framework-specific navigate/subscribe/unsubscribe behavior.
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+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 [Play RFC](../docs/rfc/play.md), this package implements:
 
 - **Actor Authority (INV-01):** Routes derive from machine definitions, not external configuration
 
@@ -27,13 +29,32 @@ npm install @xmachines/play-router
 
 **Peer dependencies:**
 
-- `xstate` ^5.0.0 - State machine runtime
+- `xstate` ^5.0.0 — State machine runtime
+
+**URLPattern polyfill (Node.js < 24 / older browsers):**
+
+`@xmachines/play-router` uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for dynamic route matching. URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+).
+
+On environments without native support, load a polyfill **before** importing this package:
+
+```typescript
+// Entry point — must run before any @xmachines/play-router import
+import "urlpattern-polyfill";
+```
+
+Install the polyfill:
+
+```bash
+npm install urlpattern-polyfill
+```
+
+`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({
@@ -65,11 +86,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"
 ```
 
@@ -159,6 +180,17 @@ Bridge teardown must be explicit and deterministic:
 - `disconnect`/`dispose` must unwatch signal subscriptions and unhook router listeners.
 - Do not rely on GC-only cleanup guidance.
 - Infrastructure remains passive: bridges observe and forward intents, actors decide validity.
+- `createBrowserHistory().destroy()` is idempotent and restores shared `window.history` patches only after the last wrapper for that window is removed.
+
+## Diagnostics
+
+Router infrastructure reports runtime failures through `PlayDiagnostics` from `@xmachines/play`.
+
+- Default behavior uses `consoleDiagnostics`.
+- Messages follow a stable `[scope:code] message` format.
+- Example: `[RouterBridgeBase:PLAY_ROUTER_SYNC_FAILED] Failed to sync actor state from router location.`
+
+This keeps router errors observable while letting applications swap in their own diagnostics implementation upstream.
 
 ## API Reference
 
@@ -176,9 +208,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)
 
@@ -190,57 +223,85 @@ 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");
 
-// Check if route exists
+// All routable routes as flat array
+const allRoutes = getRoutableRoutes(tree);
+
+// Check path exists
 const exists = routeExists(tree, "/profile/:userId");
-```
 
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-router)
+// 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
 
 ### Route Detection
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { extractMachineRoutes, findRouteByPath } from "@xmachines/play-router";
 import { createMachine } from "xstate";
 
 const machine = createMachine({
@@ -264,10 +325,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"
 ```
 
@@ -311,14 +372,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: {
@@ -336,13 +397,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)
 ```
 
@@ -388,7 +449,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"
 			},
 		},
@@ -409,20 +470,78 @@ 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
+are exported from the `./errors` subpath:
+
+```typescript
+import {
+	RouterSyncError,
+	URLPatternUnavailableError,
+	InvalidRoutePatternError,
+} from "@xmachines/play-router/errors";
+```
+
+| Class                        | Code                                    | When thrown                                                    |
+| ---------------------------- | --------------------------------------- | -------------------------------------------------------------- |
+| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` fails to send a `play.route` event     |
+| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | `createRouteMap()` called before URLPattern polyfill is loaded |
+| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern string is rejected by URLPattern constructor   |
+
+`InvalidRoutePatternError` carries a `pattern: string` field with the offending pattern.
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { RouterSyncError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof RouterSyncError) {
+		// err.cause — the original error that triggered the sync failure
+		monitoringService.record(err);
+	} else if (err instanceof PlayError) {
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	}
+}
+```
+
 ## Architecture
 
 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
 
@@ -433,4 +552,7 @@ This package enables **Actor Authority (INV-01)**:
 
 ## License
 
-MIT
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.

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

@@ -0,0 +1,116 @@
+/**
+ * BaseRouteMap — Shared bidirectional route mapping base class
+ *
+ * Provides bucket-based pattern matching shared across all framework adapters.
+ * Adapters extend this class rather than duplicating the pattern-match logic.
+ *
+ * Algorithm: O(1) exact match via Map, then bucket-based O(k) pattern match
+ * where k = routes in the first-segment bucket (typically << total routes).
+ * Uses URLPattern for parameterized route matching (same engine as createRouteMap).
+ */
+/**
+ * A single state ID ↔ path mapping entry.
+ *
+ * Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+ * Adapter packages re-export a structurally compatible `RouteMapping` type under
+ * their own name. This type is published from `@xmachines/play-router` as
+ * `BaseRouteMapping` to avoid name collisions with those adapter-local types.
+ *
+ * @example
+ * ```typescript
+ * const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
+ * const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
+ * const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+ * ```
+ */
+export interface RouteMapping {
+    /** State machine state ID (e.g., `"home"`, `"#profile"`) */
+    readonly stateId: string;
+    /** URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) */
+    readonly path: string;
+}
+/**
+ * Shared bidirectional route map base class.
+ *
+ * All framework adapter `RouteMap` classes extend this — they add no logic of their
+ * own and inherit the full public API from here.
+ *
+ * **Lookup strategy:**
+ * - Static paths (no `:param`) → O(1) `Map` lookup
+ * - Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
+ *   of routes sharing the same first path segment
+ * - Results are cached after the first match
+ *
+ * **Pattern syntax** (`:param` / `:param?`):
+ * - `:param` — required segment, matches exactly one non-`/` segment
+ * - `:param?` — optional segment, matches zero or one non-`/` segment
+ *
+ * @example
+ * ```typescript
+ * import { BaseRouteMap } from "@xmachines/play-router";
+ *
+ * const map = new BaseRouteMap([
+ *   { stateId: "home",     path: "/" },
+ *   { stateId: "profile",  path: "/profile/:userId" },
+ *   { stateId: "settings", path: "/settings/:section?" },
+ * ]);
+ *
+ * map.getStateIdByPath("/");               // "home"
+ * map.getStateIdByPath("/profile/123");    // "profile"
+ * map.getStateIdByPath("/settings");       // "settings"
+ * map.getStateIdByPath("/unknown");        // null
+ *
+ * map.getPathByStateId("profile");         // "/profile/:userId"
+ * map.getPathByStateId("missing");         // null
+ * ```
+ */
+export declare class BaseRouteMap {
+    private stateIdToPath;
+    private pathToStateId;
+    private patternBuckets;
+    private pathMatchCache;
+    /**
+     * Build a route map from an array of state ID ↔ path mappings.
+     *
+     * Static paths (no `:param`) are indexed in an O(1) `Map`.
+     * Parameterized paths are compiled to `URLPattern` and grouped into first-segment
+     * buckets for efficient candidate selection.
+     *
+     * @param mappings - Array of `{ stateId, path }` entries. Order determines
+     *   priority when multiple patterns could match the same path.
+     */
+    constructor(mappings: RouteMapping[]);
+    /**
+     * Resolve a URL path to its mapped state ID.
+     *
+     * Strips query strings and hash fragments before matching. Tries an O(1) exact
+     * lookup first, then falls back to bucket-indexed pattern matching. Results are
+     * cached after the first pattern match.
+     *
+     * @param path - URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`)
+     * @returns The mapped state ID, or `null` if no route matches
+     *
+     * @example
+     * ```typescript
+     * map.getStateIdByPath("/profile/123");  // "profile"
+     * map.getStateIdByPath("/unknown");      // null
+     * ```
+     */
+    getStateIdByPath(path: string): string | null;
+    /**
+     * Look up the path pattern registered for a state ID.
+     *
+     * @param stateId - State machine state ID (e.g., `"profile"`, `"#settings"`)
+     * @returns The registered path pattern, or `null` if the state ID is unknown
+     *
+     * @example
+     * ```typescript
+     * map.getPathByStateId("profile");   // "/profile/:userId"
+     * map.getPathByStateId("missing");   // null
+     * ```
+     */
+    getPathByStateId(stateId: string): string | null;
+    private getIndexKey;
+    private getCandidates;
+}
+//# sourceMappingURL=base-route-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAuCH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;OASG;gBACS,QAAQ,EAAE,YAAY,EAAE;IAkCpC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB7C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIhD,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,aAAa;CA8BrB"}