@xmachines/docs 1.0.0-beta.43 → 1.0.0-beta.44

package/api/@xmachines/play-react-router/interfaces/RouteMapOptions.md

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / RouteMapOptions
+
+# Interface: RouteMapOptions
+
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/create-route-map.ts#L9)
+
+Options for `createRouteMap` and `createRouteMapFromTree`.
+
+## Properties
+
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                  |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/create-route-map.ts#L20) |

package/api/@xmachines/play-react-router/interfaces/RouteMapping.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/base-route-map.ts#L57)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
 | --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/base-route-map.ts#L61) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/base-route-map.ts#L59) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/base-route-map.ts#L59) |

package/api/@xmachines/play-react-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/types.ts#L271)
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -44,7 +44,7 @@ class TanStackRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../docs/rfc/play.md) - Invariant INV-04
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
 
 ## Methods
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/types.ts#L287)
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/types.ts#L303)
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

@@ -16,7 +16,7 @@ It also exports `RouterBridgeBase`, the shared base class used by framework adap
 
 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:
+Per [Play RFC](../../../rfc/play.md), this package implements:
 
 - **Actor Authority (INV-01):** Routes derive from machine definitions, not external configuration
 
@@ -126,7 +126,7 @@ Open http://localhost:5174/ and explore:
 ```typescript
 // Extract routes from machine
 const routeTree = extractMachineRoutes(authMachine);
-const routeMatcher = createRouteMap(routeTree);
+const routeMatcher = createRouteMatcher(routeTree);
 
 // Actor → URL sync
 const watcher = new Signal.subtle.Watcher(() => {
@@ -197,7 +197,7 @@ 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.
+Actor-originated router sync suppresses router echoes via `lastSyncedPath`. `syncRouterFromActor` resolves the concrete path and stores it before calling the adapter's navigation method; when the router callback fires with that same path, `syncActorFromRouter` short-circuits at `sanitized === lastSyncedPath` and sends no event.
 
 ## Diagnostics
 
@@ -293,14 +293,14 @@ const successors = getSuccessors(tree.graph!, "myMachine.home");
 - `eventType: string` — event type triggering this transition
 - `guardType?: string` — guard name/description (if transition is guarded)
 
-### createRouteMapFromMachine() / createRouteMapFromTree()
+### createRouteMap() / 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);
+import { createRouteMap } from "@xmachines/play-router";
+const routeMap = createRouteMap(machine);
 
 // Two-step form — used by framework adapter packages:
 import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
@@ -308,7 +308,7 @@ 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).
+Both forms produce identical `RouteMap` results. `createRouteMapFromTree` is exposed for framework adapters (React Router, TanStack Router) that already hold the `RouteTree` separately for other purposes (e.g. graph queries). `createRouteMatcher(routeTree)` is the distinct API for URL-pattern matching that returns a `RouteMatcher`, not a `RouteMap`.
 
 **`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.
 
@@ -613,6 +613,7 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [MachineNodeData](interfaces/MachineNodeData.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RouteInfo](interfaces/RouteInfo.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouteMatch](interfaces/RouteMatch.md)
 - [RouteMatcher](interfaces/RouteMatcher.md)
@@ -633,8 +634,8 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [buildPlayRouteEvent](functions/buildPlayRouteEvent.md)
 - [buildRouteTree](functions/buildRouteTree.md)
 - [createRouteMap](functions/createRouteMap.md)
-- [createRouteMapFromMachine](functions/createRouteMapFromMachine.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
+- [createRouteMatcher](functions/createRouteMatcher.md)
 - [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
 - [extractMachineRoutes](functions/extractMachineRoutes.md)
 - [extractQuery](functions/extractQuery.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -50,7 +50,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/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.44/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -109,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/base-route-map.ts#L174)
 
 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:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L89)
+Defined in: [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L101)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -30,14 +30,14 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L103)
+Defined in: [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L125)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                      |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `actor`                     | [`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) | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                                                                                                                                              | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. |
+| Parameter                   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                             |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor`                     | [`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) | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                                  |
+| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                                                                                                                                              | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. |
 | `routeMap.getPathByStateId` | -                                                                                                                                                                                                                                                                |
 | `routeMap.getStateIdByPath` | -                                                                                                                                                                                                                                                                |
 
@@ -47,17 +47,17 @@ Defined in: [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-
 
 ## Properties
 
-| 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:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L92)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L91)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L94)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L93)   |
-| <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:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L105) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L107) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L106) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L95)   |
+| 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:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L126) |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L104) |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L103) |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L116) |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L105) |
+| <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(machine)` or an equivalent.                                                                                                                                                                                                                                                                                                | [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L127) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L129) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L128) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L117) |
 
 ## Methods
 
@@ -67,7 +67,7 @@ Defined in: [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L131)
+Defined in: [router-bridge-base.ts:153](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L153)
 
 Connect the router bridge to the Actor.
 
@@ -99,7 +99,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L218)
+Defined in: [router-bridge-base.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L249)
 
 Disconnect the router bridge from the Actor.
 
@@ -121,7 +121,7 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:326](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L326)
+Defined in: [router-bridge-base.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L373)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -155,7 +155,7 @@ When URLPattern is absent and the route is parameterized
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:363](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L363)
+Defined in: [router-bridge-base.ts:410](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L410)
 
 Extract query parameters from URL search string.
 
@@ -179,7 +179,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:420](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L420)
+Defined in: [router-bridge-base.ts:467](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L467)
 
 Return the router's current pathname at connect() time.
 
@@ -211,7 +211,7 @@ bridges that have not yet implemented this hook.
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:437](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L437)
+Defined in: [router-bridge-base.ts:484](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L484)
 
 Return the router's current search string at connect() time.
 
@@ -237,7 +237,7 @@ URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
 abstract protected navigateRouter(path): void;
 ```
 
-Defined in: [router-bridge-base.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L375)
+Defined in: [router-bridge-base.ts:422](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L422)
 
 Navigate the framework router to the given path.
 
@@ -262,7 +262,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [router-bridge-base.ts:348](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L348)
+Defined in: [router-bridge-base.ts:395](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L395)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -297,7 +297,7 @@ Concrete URL path, or `null` if navigation should be skipped
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [router-bridge-base.ts:268](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L268)
+Defined in: [router-bridge-base.ts:315](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L315)
 
 Sync actor state when router location changes.
 
@@ -323,16 +323,20 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [router-bridge-base.ts:290](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L290)
 
 Sync router location when actor route signal changes.
 
 Calls navigateRouter() for framework-specific navigation.
-Prevents circular updates via isProcessingNavigation flag.
 
-`lastSyncedPath` is updated before `navigateRouter()` and the processing flag is
-released in a microtask so synchronous router callbacks triggered by navigation are
-suppressed as circular echoes.
+Echo suppression — preventing the router's own callback from re-driving the
+actor — is handled entirely by `lastSyncedPath`: it is set to `route` before
+`navigateRouter()` is called, so any `syncActorFromRouter` invocation for the
+same path short-circuits at the `sanitized === lastSyncedPath` check and sends
+no event regardless of whether the callback fires synchronously or asynchronously.
+
+`isProcessingNavigation` is NOT set here — it is only used inside
+`syncActorFromRouter` to guard against re-entrant guard-redirect loops.
 
 #### Parameters
 
@@ -352,7 +356,7 @@ suppressed as circular echoes.
 abstract protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:400](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L400)
+Defined in: [router-bridge-base.ts:447](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L447)
 
 Stop watching for router location changes.
 
@@ -370,7 +374,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 abstract protected watchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:393](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-bridge-base.ts#L393)
+Defined in: [router-bridge-base.ts:440](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-bridge-base.ts#L440)
 
 Start watching for router location changes.
 

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

@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [router-sync.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/router-sync.ts#L140)
+Defined in: [router-sync.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/router-sync.ts#L140)
 
 Build a normalized `play.route` event from raw router/browser input.
 

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.43/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.44/packages/play-router/src/build-tree.ts#L13)
 
 Build hierarchical route tree from flat route list
 

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

@@ -3,51 +3,37 @@
 # Function: createRouteMap()
 
 ```ts
-function createRouteMap(routeTree): RouteMatcher;
+function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/create-route-map.ts#L74)
+Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/create-route-map.ts#L45)
 
-Create a route matcher from a RouteTree for efficient path lookups.
+Create a `RouteMap` from an XState state machine.
 
-Architecture:
+Extracts all routable states (those with `meta.route`) and builds a bidirectional
+path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
+subclasses to translate browser URL changes into `play.route` actor events and
+vice-versa.
 
-- Pure function - no side effects
-- O(1) lookups for exact matches via Map
-- O(k) bucket-indexed pattern matching with URLPattern, where k = routes in the
-  first-segment bucket (typically << total routes)
-- Returns formatted state IDs (with # prefix)
-- Extracts params from matched patterns
+## Parameters
 
-**URLPattern requirement:** Dynamic route pattern matching requires `URLPattern`
-to be available on `globalThis`. On Node.js < 24 and older browsers, load a polyfill
-before calling this function:
+| Parameter  | Type                                                                      | Description                                                                                                         |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
 
-```typescript
-import "urlpattern-polyfill"; // before importing @xmachines/play-router
-```
+## Returns
+
+[`RouteMap`](../classes/RouteMap.md)
 
-If `URLPattern` is unavailable, a `URLPatternUnavailableError` is thrown.
-Static (exact) routes are unaffected by URLPattern availability.
+A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
 
-Usage:
+## Example
 
 ```typescript
-const routeTree = extractMachineRoutes(machine);
-const routeMatcher = createRouteMap(routeTree);
+import { createRouteMap } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
 
-const { to, params } = routeMatcher.match("/settings/account");
-if (to) {
-	actor.send({ type: "play.route", to, params });
-}
+const routeMap = createRouteMap(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
 ```
-
-## Parameters
-
-| Parameter   | Type                                      |
-| ----------- | ----------------------------------------- |
-| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md) |
-
-## Returns
-
-[`RouteMatcher`](../interfaces/RouteMatcher.md)

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

@@ -3,27 +3,28 @@
 # Function: createRouteMapFromTree()
 
 ```ts
-function createRouteMapFromTree(routeTree): RouteMap;
+function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [create-route-map-from-tree.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.43/packages/play-router/src/create-route-map-from-tree.ts#L31)
+Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
 Create a `RouteMap` from a `RouteTree` node structure.
 
 Used by framework-router adapters (React Router, TanStack Router) that pass a
 `RouteTree` produced by `extractMachineRoutes()` rather than calling
-`createRouteMapFromMachine()` directly.
+`createRouteMap()` directly.
 
 Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
 `node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
 which is what `RouteMap` needs for browser URL matching. This matches the
-behaviour of `createRouteMapFromMachine`, which also uses `node.fullPath`.
+behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
 
 ## Parameters
 
-| Parameter   | Type                                      | Description                                            |
-| ----------- | ----------------------------------------- | ------------------------------------------------------ |
-| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md) | A `RouteTree` as returned by `extractMachineRoutes()`. |
+| Parameter   | Type                                                  | Description                                                                   |
+| ----------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md)             | A `RouteTree` as returned by `extractMachineRoutes()`.                        |
+| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size). |
 
 ## Returns
 
@@ -35,10 +36,10 @@ A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
 
 ```typescript
 // Preferred — single call for XState machines:
-import { createRouteMapFromMachine } from "@xmachines/play-router";
-const routeMap = createRouteMapFromMachine(machine);
+import { createRouteMap } from "@xmachines/play-router";
+const routeMap = createRouteMap(machine); // takes AnyStateMachine
 
-// Equivalent two-step form used by framework adapters:
+// Two-step form used by framework adapters that work with route trees:
 import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)

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

@@ -0,0 +1,53 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMatcher
+
+# Function: createRouteMatcher()
+
+```ts
+function createRouteMatcher(routeTree): RouteMatcher;
+```
+
+Defined in: [create-route-matcher.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.44/packages/play-router/src/create-route-matcher.ts#L74)
+
+Create a URL pattern matcher from a RouteTree for efficient path lookups.
+
+Architecture:
+
+- Pure function - no side effects
+- O(1) lookups for exact matches via Map
+- O(k) bucket-indexed pattern matching with URLPattern, where k = routes in the
+  first-segment bucket (typically << total routes)
+- Returns formatted state IDs (with # prefix)
+- Extracts params from matched patterns
+
+**URLPattern requirement:** Dynamic route pattern matching requires `URLPattern`
+to be available on `globalThis`. On Node.js < 24 and older browsers, load a polyfill
+before calling this function:
+
+```typescript
+import "urlpattern-polyfill"; // before importing @xmachines/play-router
+```
+
+If `URLPattern` is unavailable, a `URLPatternUnavailableError` is thrown.
+Static (exact) routes are unaffected by URLPattern availability.
+
+Usage:
+
+```typescript
+const routeTree = extractMachineRoutes(machine);
+const routeMatcher = createRouteMatcher(routeTree);
+
+const { to, params } = routeMatcher.match("/settings/account");
+if (to) {
+	actor.send({ type: "play.route", to, params });
+}
+```
+
+## Parameters
+
+| Parameter   | Type                                      |
+| ----------- | ----------------------------------------- |
+| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md) |
+
+## Returns
+
+[`RouteMatcher`](../interfaces/RouteMatcher.md)

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

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