@xmachines/play-router 1.0.0-beta.4 → 1.0.0-beta.41

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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()` from `@xmachines/play-dom-router` 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"
 ```
 
@@ -88,9 +109,7 @@ The demo demonstrates:
 **Run the demo:**
 
 ```bash
-cd packages/play-router/examples/demo
-npm install
-npm run dev
+npm run dev -w @xmachines/play-dom-router-demo
 ```
 
 Open http://localhost:5174/ and explore:
@@ -105,7 +124,7 @@ Open http://localhost:5174/ and explore:
 ```typescript
 // Extract routes from machine
 const routeTree = extractMachineRoutes(authMachine);
-const routeMap = createRouteMap(routeTree);
+const routeMatcher = createRouteMap(routeTree);
 
 // Actor → URL sync
 const watcher = new Signal.subtle.Watcher(() => {
@@ -122,7 +141,7 @@ const watcher = new Signal.subtle.Watcher(() => {
 // URL → Actor sync (with pattern matching)
 window.addEventListener("popstate", () => {
 	const path = window.location.pathname;
-	const { to, params } = routeMap.resolve(path);
+	const { to, params } = routeMatcher.match(path);
 	if (to) {
 		actor.send({ type: "play.route", to, params });
 	}
@@ -131,7 +150,7 @@ window.addEventListener("popstate", () => {
 // Initial URL handling
 const initialPath = window.location.pathname;
 if (initialPath !== "/") {
-	const { to, params } = routeMap.resolve(initialPath);
+	const { to, params } = routeMatcher.match(initialPath);
 	if (to) {
 		actor.send({ type: "play.route", to, params });
 	}
@@ -159,6 +178,34 @@ 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()` (from `@xmachines/play-dom-router`) is idempotent and restores shared `window.history` patches only after the last wrapper for that window is removed.
+    - **Note**: `createBrowserHistory()` mutates global `window.history` methods (`pushState` and `replaceState`) and coordinates wrappers with shared ref-count state. To reduce leakage, create one history wrapper per browser window at the application boundary and always pair it with `destroy()` during teardown.
+
+## Bridge Sync Ordering
+
+`RouterBridgeBase.connect()` has an intentional ordering contract used by all framework adapters:
+
+- seed `lastSyncedPath` from `actor.currentRoute` in the constructor
+- install the actor route watcher
+- install adapter router subscriptions
+- resolve initial sync using `getInitialRouterPath()` and `actor.initialRoute`
+
+That final step distinguishes:
+
+- **deep-link:** browser URL differs from the machine's initial route, so router wins and the actor receives `play.route`
+- **restore:** browser URL is still at the machine's initial route while the actor was restored elsewhere, so actor wins and the bridge pushes the actor route back into the router
+
+Actor-originated router sync also keeps `isProcessingNavigation` set until the next microtask. That short window intentionally suppresses synchronous router callbacks that echo the same navigation back into the actor.
+
+## 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 +223,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)
 
@@ -189,58 +237,112 @@ import { extractMachineRoutes } from "@xmachines/play-router";
 
 const tree = extractMachineRoutes(authMachine);
 
-// Query routes
-const loginRoute = tree.byId.get("login");
-console.log(loginRoute?.path); // "/login"
+// Query routes — use fullPath for URL matching (path is the raw meta.route segment)
+const loginRoute = tree.byStateId.get("login");
+console.log(loginRoute?.fullPath); // "/login"
+console.log(loginRoute?.path); // "/login" (same for absolute routes)
+
+// For nested relative routes the distinction matters:
+// meta.route: "overview" under "/dashboard" → path: "overview", fullPath: "/dashboard/overview"
+const overviewRoute = tree.byStateId.get("overview");
+console.log(overviewRoute?.path); // "overview"  (raw segment — relative)
+console.log(overviewRoute?.fullPath); // "/dashboard/overview"  (resolved — use this)
 
 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)
+
+### createRouteMapFromMachine() / createRouteMapFromTree()
+
+Both build a `BaseRouteMap` using `node.fullPath` (absolute resolved paths) for browser URL matching.
+
+```typescript
+// Single-call form — preferred for XState machines:
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+const routeMap = createRouteMapFromMachine(machine);
+
+// Two-step form — used by framework adapter packages:
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
 ```
 
+Both forms produce identical results. `createRouteMapFromTree` is exposed for framework adapters (React Router, TanStack Router) that need to hold the `RouteTree` separately for other purposes (e.g. graph queries).
+
+**`node.path` vs `node.fullPath`:** Every `RouteNode` carries both fields. `path` is the raw `meta.route` segment as declared in the machine — it may be relative (e.g. `"overview"`). `fullPath` is the resolved absolute path (e.g. `"/dashboard/overview"`). Route maps always use `fullPath`. Only use `path` if you specifically need the declared segment.
+
 ### 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({
@@ -263,11 +365,11 @@ const machine = createMachine({
 
 const tree = extractMachineRoutes(machine);
 
-// Bidirectional mapping
-const profileById = tree.byId.get("profile");
-console.log(profileById?.path); // "/profile/:userId"
+// Bidirectional mapping — use fullPath for URLs; path is the raw meta.route segment
+const profileById = tree.byStateId.get("profile");
+console.log(profileById?.fullPath); // "/profile/:userId"
 
-const profileByPath = tree.byPath.get("/profile/user123");
+const profileByPath = findRouteByPath(tree, "/profile/user123");
 console.log(profileByPath?.id); // "profile"
 ```
 
@@ -311,14 +413,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 +438,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 +490,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 +511,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 +593,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,123 @@
+/**
+ * RouteMap — 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 `RouteMap`.
+ * Adapter packages re-export a structurally compatible `RouteMapping` type under
+ * their own name. This type is published from `@xmachines/play-router` as
+ * `RouteMapping` to avoid name collisions with those adapter-local types.
+ *
+ * @example
+ * ```typescript
+ * const mapping: RouteMapping = { stateId: "home", path: "/" };
+ * const paramMapping: RouteMapping = { stateId: "profile", path: "/profile/:userId" };
+ * const optionalMapping: RouteMapping = { 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 adapters use this class as their route map — 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 in an LRU cache (default 500 entries,
+ *   configurable via the `cacheSize` constructor option)
+ *
+ * **Pattern syntax** (`:param` / `:param?`):
+ * - `:param` — required segment, matches exactly one non-`/` segment
+ * - `:param?` — optional segment, matches zero or one non-`/` segment
+ *
+ * @example
+ * ```typescript
+ * import { RouteMap } from "@xmachines/play-router";
+ *
+ * const map = new RouteMap([
+ *   { 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 RouteMap {
+    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.
+     * @param options - Optional configuration.
+     *   `options.cacheSize`: Maximum number of resolved parameterized path lookups
+     *   to cache. Defaults to `500`. Increase for applications with many unique
+     *   parameterized URL values (e.g. user profile pages with thousands of distinct IDs).
+     *   After eviction the path falls back to the O(k) bucket pattern scan — correct
+     *   but slower. Minimum effective value is `1` (QuickLRU constraint).
+     */
+    constructor(mappings: RouteMapping[], { cacheSize }?: {
+        cacheSize?: number;
+    });
+    /**
+     * 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;
+}
+//# 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;AAgCH;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,QAAQ;IACpB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;;;;;;;OAeG;gBACS,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,SAAe,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAiCtF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB7C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD"}