@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,149 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L101)
+
+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
+- `*` — wildcard, matches any number of segments (URLPattern semantics)
+
+**StateId forms:** stateIds may be registered and looked up in either
+`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+`getStateIdByPath` returns the stateId exactly as registered;
+`getPathByStateId` accepts both forms. Registering the same stateId in both
+forms refers to one entry (the later registration wins for reverse lookup).
+
+## 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
+```
+
+## Constructors
+
+### Constructor
+
+```ts
+new RouteMap(mappings, options?): RouteMap;
+```
+
+Defined in: [base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L127)
+
+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.
+
+#### Parameters
+
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | 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). |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+#### Returns
+
+`RouteMap`
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+Defined in: [base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L218)
+
+Look up the path pattern registered for a state ID.
+
+Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+which form was used at registration — lookups are canonicalized internally,
+so consumers never need to try both forms.
+
+#### Parameters
+
+| Parameter | Type     | Description                                               |
+| --------- | -------- | --------------------------------------------------------- |
+| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The registered path pattern, or `null` if the state ID is unknown
+
+#### Example
+
+```typescript
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
+map.getPathByStateId("missing"); // null
+```
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+Defined in: [base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L178)
+
+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.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------ |
+| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The mapped state ID, or `null` if no route matches
+
+#### Example
+
+```typescript
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/unknown"); // null
+```

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

@@ -1,8 +1,8 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouterBridgeBase
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouterBridgeBase
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L56)
+Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-bridge-base.ts#L96)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -13,9 +13,9 @@ between frameworks.
 ## Extended by
 
 - [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
+- [`TanStackRouterBridgeBase`](../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
 - [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
 - [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
-- [`SolidRouterBridge`](../../play-tanstack-solid-router/classes/SolidRouterBridge.md)
 - [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
 
 ## Implements
@@ -30,37 +30,21 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L70)
-
-Constructor receives the 3 things all bridges need.
+Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-bridge-base.ts#L123)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                                    | Description                                           |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `actor`                     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | Actor with currentRoute signal and send method        |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                     | Bidirectional route map for stateId ↔ path resolution |
-| `routeMap.getPathByStateId` | -                                                                                                                                       |
-| `routeMap.getStateIdByPath` | -                                                                                                                                       |
+| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, 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. `getPathByStateId` may be keyed on either the `"#stateId"` or the bare `"stateId"` form — both forms are tried automatically by the bridge, so custom implementations (e.g. plain test objects) need only handle one. |
+| `routeMap.getPathByStateId` | -                                                                                                                   |
+| `routeMap.getStateIdByPath` | -                                                                                                                   |
 
 #### Returns
 
 `RouterBridgeBase`
 
-## Properties
-
-| Property                                                              | Modifier    | Type                                                                                                                                    | Default value | Description                                           | Defined in                                                                                                                                                                |
-| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | Actor with currentRoute signal and send method        | [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L71) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                               | `false`       | -                                                     | [router-bridge-base.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L59) |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                               | `false`       | -                                                     | [router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L58) |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                               | `false`       | -                                                     | [router-bridge-base.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L61) |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string`                                                                                                                                | `""`          | -                                                     | [router-bridge-base.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L60) |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                | `undefined`   | Bidirectional route map for stateId ↔ path resolution | [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L72) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                       | `undefined`   | -                                                     | [router-bridge-base.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L74) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                       | `undefined`   | -                                                     | [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L73) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`Watcher`](../../play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md) \| `null`                                     | `null`        | -                                                     | [router-bridge-base.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L62) |
-
 ## Methods
 
 ### connect()
@@ -69,13 +53,22 @@ Constructor receives the 3 things all bridges need.
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L90)
+Defined in: [router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-bridge-base.ts#L151)
 
 Connect the router bridge to the Actor.
 
 Sets up the TC39 Signal watcher for actor → router direction and
 starts watching router changes (framework-specific).
 
+Ordering here is part of the bridge contract:
+
+- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
+- the actor watcher is installed before adapter router subscriptions
+- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+
+Adapters that need custom initial-sync behavior should override
+`getInitialRouterPath()` rather than reordering `connect()` steps.
+
 #### Returns
 
 `void`
@@ -92,7 +85,7 @@ starts watching router changes (framework-specific).
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L140)
+Defined in: [router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-bridge-base.ts#L256)
 
 Disconnect the router bridge from the Actor.
 
@@ -105,196 +98,3 @@ Stops signal watching and unregisters framework-specific router listener.
 #### Implementation of
 
 [`RouterBridge`](../interfaces/RouterBridge.md).[`disconnect`](../interfaces/RouterBridge.md#disconnect)
-
----
-
-### extractParams()
-
-```ts
-protected extractParams(pathname, stateId): Record<string, string>;
-```
-
-Defined in: [router-bridge-base.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L276)
-
-Extract path parameters from URL using the URLPattern API.
-
-Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-library. If `URLPattern` is unavailable (Node.js < 24, older browsers without a
-polyfill), this method returns `{}` silently (graceful degradation — routing still
-works, params will be empty).
-
-#### Parameters
-
-| Parameter  | Type     | Description                                       |
-| ---------- | -------- | ------------------------------------------------- |
-| `pathname` | `string` | The actual URL path (e.g., '/profile/john')       |
-| `stateId`  | `string` | The matched state ID for looking up route pattern |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted path parameters, or empty object if URLPattern is unavailable or no match
-
----
-
-### extractQuery()
-
-```ts
-protected extractQuery(search): Record<string, string>;
-```
-
-Defined in: [router-bridge-base.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L303)
-
-Extract query parameters from URL search string.
-
-#### Parameters
-
-| Parameter | Type     | Description                                      |
-| --------- | -------- | ------------------------------------------------ |
-| `search`  | `string` | URL search string (e.g., '?tab=security&page=1') |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted query parameters or empty object
-
----
-
-### getInitialRouterPath()
-
-```ts
-protected getInitialRouterPath(): string | null;
-```
-
-Defined in: [router-bridge-base.ts:353](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L353)
-
-Return the router's current pathname at connect() time, or null if unavailable.
-
-Called once during connect() to perform the initial URL → actor sync.
-router.subscribe() only fires on _future_ navigation events; it does not
-replay the already-loaded location. Subclasses that can read the router's
-current location synchronously (e.g. `router.state.location.pathname`)
-should override this method so that deep-link / direct-URL loads drive the
-actor to the correct state instead of leaving it at its machine default.
-
-The default returns null (no initial router → actor sync), preserving the
-previous behaviour for bridges that have not yet implemented this hook.
-
-#### Returns
-
-`string` \| `null`
-
----
-
-### navigateRouter()
-
-```ts
-abstract protected navigateRouter(path): void;
-```
-
-Defined in: [router-bridge-base.ts:323](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L323)
-
-Navigate the framework router to the given path.
-
-Called when actor's currentRoute signal changes to a new path.
-Must trigger the framework router's navigation (e.g., router.navigate(path)).
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-#### Returns
-
-`void`
-
----
-
-### syncActorFromRouter()
-
-```ts
-protected syncActorFromRouter(pathname, search?): void;
-```
-
-Defined in: [router-bridge-base.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L187)
-
-Sync actor state when router location changes.
-
-Sends play.route event to actor with resolved stateId, params, and query.
-Prevents circular updates via isProcessingNavigation flag.
-
-#### Parameters
-
-| Parameter  | Type     |
-| ---------- | -------- |
-| `pathname` | `string` |
-| `search?`  | `string` |
-
-#### Returns
-
-`void`
-
----
-
-### syncRouterFromActor()
-
-```ts
-protected syncRouterFromActor(route): void;
-```
-
-Defined in: [router-bridge-base.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L167)
-
-Sync router location when actor route signal changes.
-
-Calls navigateRouter() for framework-specific navigation.
-Prevents circular updates via isProcessingNavigation flag.
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `route`   | `unknown` |
-
-#### Returns
-
-`void`
-
----
-
-### unwatchRouterChanges()
-
-```ts
-abstract protected unwatchRouterChanges(): void;
-```
-
-Defined in: [router-bridge-base.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L338)
-
-Stop watching for router location changes.
-
-Called by disconnect(). Should clean up the framework-specific subscription.
-
-#### Returns
-
-`void`
-
----
-
-### watchRouterChanges()
-
-```ts
-abstract protected watchRouterChanges(): void;
-```
-
-Defined in: [router-bridge-base.ts:331](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/router-bridge-base.ts#L331)
-
-Start watching for router location changes.
-
-Called by connect(). Should set up the framework-specific subscription
-for location changes and call syncActorFromRouter() on each change.
-
-#### Returns
-
-`void`

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

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / buildPlayRouteEvent
+
+# Function: buildPlayRouteEvent()
+
+```ts
+function buildPlayRouteEvent(options): {
+	event: PlayRouteEvent;
+	pathname: string;
+} | null;
+```
+
+Defined in: [router-sync.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/router-sync.ts#L168)
+
+Build a normalized `play.route` event from raw router/browser input.
+
+Both `connectRouter()` (from `@xmachines/play-dom-router`) and `RouterBridgeBase`
+use this helper so low-level and framework adapters share the same pathname
+sanitization, route matching, and query extraction behavior.
+
+## Parameters
+
+| Parameter | Type                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `options` | [`BuildPlayRouteEventOptions`](../interfaces/BuildPlayRouteEventOptions.md) |
+
+## Returns
+
+\| \{
+`event`: [`PlayRouteEvent`](../interfaces/PlayRouteEvent.md);
+`pathname`: `string`;
+\}
+\| `null`

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

@@ -1,4 +1,4 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / buildRouteTree
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / buildRouteTree
 
 # Function: buildRouteTree()
 
@@ -6,7 +6,7 @@
 function buildRouteTree(routes): RouteTree;
 ```
 
-Defined in: [build-tree.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/build-tree.ts#L13)
+Defined in: [build-tree.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/build-tree.ts#L21)
 
 Build hierarchical route tree from flat route list
 
@@ -14,6 +14,12 @@ Constructs nested tree respecting parent-child state relationships.
 Absolute routes become top-level, relative routes nest under parents.
 Creates bidirectional maps for state ID ↔ path lookup.
 
+Duplicate detection runs here — after relative routes are resolved against
+their parent's full path — so two relative routes with the same raw string
+under different parents are valid, while distinct raw strings that resolve to
+the same full path (which would silently overwrite each other in `byPath`)
+are rejected.
+
 ## Parameters
 
 | Parameter | Type                                        | Description                            |
@@ -25,3 +31,7 @@ Creates bidirectional maps for state ID ↔ path lookup.
 [`RouteTree`](../interfaces/RouteTree.md)
 
 RouteTree with root, byStateId map, and byPath map
+
+## Throws
+
+If two states resolve to the same full path

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

@@ -1,53 +1,39 @@
-[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMap
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMap
 
 # Function: createRouteMap()
 
 ```ts
-function createRouteMap(routeTree): RouteMap;
+function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-router/src/create-route-map.ts#L120)
+Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/create-route-map.ts#L45)
 
-Create a RouteMap 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, parameterized routes will not match and a
-`console.warn` is emitted. Static (exact) routes are unaffected.
+A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
 
-Usage:
+## Example
 
 ```typescript
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMap(routeTree);
+import { createRouteMap } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
 
-const { to, params } = routeMap.resolve("/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
-
-[`RouteMap`](../interfaces/RouteMap.md)

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

@@ -0,0 +1,46 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromTree
+
+# Function: createRouteMapFromTree()
+
+```ts
+function createRouteMapFromTree(routeTree, options?): RouteMap;
+```
+
+Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
+
+Create a `RouteMap` from a `RouteTree` node structure.
+
+Used by framework-router adapters that pass a
+`RouteTree` produced by `extractMachineRoutes()` rather than calling
+`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 `createRouteMap(machine)`, which also uses `node.fullPath`.
+
+## Parameters
+
+| 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
+
+[`RouteMap`](../classes/RouteMap.md)
+
+A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+// Preferred — single call for XState machines:
+import { createRouteMap } from "@xmachines/play-router";
+const routeMap = createRouteMap(machine); // takes AnyStateMachine
+
+// 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)
+```