@xmachines/docs 1.0.0-beta.53 → 1.0.0-beta.55

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L100)
+Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/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)
-- [`TanStackSolidRouterBridge`](../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
 - [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
 
 ## Implements
@@ -30,14 +30,14 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L124)
+Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/router-bridge-base.ts#L123)
 
 #### Parameters
 
-| 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. |
+| 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` | -                                                                                                                   |
 
@@ -45,20 +45,6 @@ Defined in: [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-
 
 `RouterBridgeBase`
 
-## Properties
-
-| Property                                                              | Modifier    | Type                                                                  | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                        |
-| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../interfaces/RoutableActor.md)                     | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L125) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L103) |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L102) |
-| <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:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L115) |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                    | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L104) |
-| <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:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L126) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L128) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L127) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null` | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L116) |
-
 ## Methods
 
 ### connect()
@@ -67,7 +53,7 @@ Defined in: [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L152)
+Defined in: [router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/router-bridge-base.ts#L151)
 
 Connect the router bridge to the Actor.
 
@@ -99,7 +85,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/router-bridge-base.ts#L256)
 
 Disconnect the router bridge from the Actor.
 
@@ -112,325 +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:402](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L402)
-
-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 and the matched route has parameterized
-segments, a `URLPatternUnavailableError` is thrown — callers must provide a polyfill
-for environments without native URLPattern support (Node.js < 24, older browsers).
-
-#### Parameters
-
-| Parameter  | Type     | Description                                           |
-| ---------- | -------- | ----------------------------------------------------- |
-| `pathname` | `string` | The actual URL path (e.g., '/profile/john')           |
-| `stateId`  | `string` | The matched state ID for looking up the route pattern |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted path parameters, or empty object if no match
-
-#### Throws
-
-When URLPattern is absent and the route is parameterized
-
----
-
-### extractQuery()
-
-```ts
-protected extractQuery(search): Record<string, string>;
-```
-
-Defined in: [router-bridge-base.ts:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L439)
-
-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 | undefined;
-```
-
-Defined in: [router-bridge-base.ts:512](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L512)
-
-Return the router's current pathname at connect() time.
-
-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.
-
-Return semantics:
-
-- `string` → router has a current path; base connect() will sync actor from router
-- `null` → router is active but has no current path yet; base connect() will sync router from actor
-- `undefined` → adapter handles initial sync itself and base connect() should stay out of the way
-
-The default returns `undefined`, preserving the previous behaviour for
-bridges that have not yet implemented this hook.
-
-#### Returns
-
-`string` \| `null` \| `undefined`
-
----
-
-### getInitialRouterSearch()
-
-```ts
-protected getInitialRouterSearch(): string | undefined;
-```
-
-Defined in: [router-bridge-base.ts:529](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L529)
-
-Return the router's current search string at connect() time.
-
-Paired with `getInitialRouterPath()` — called once during connect() to pass
-the initial URL query string to `syncActorFromRouter()`. If the router's current
-URL has no search (or the subclass doesn't override this), returns `undefined`
-and `syncActorFromRouter` will produce an empty `query: {}` in the event.
-
-Subclasses that override `getInitialRouterPath()` and have a query string
-available should also override this method.
-
-#### Returns
-
-`string` \| `undefined`
-
-URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
-
----
-
-### navigateRouter()
-
-```ts
-abstract protected navigateRouter(path): void;
-```
-
-Defined in: [router-bridge-base.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L448)
-
-Must trigger the framework router's navigation (e.g., router.navigate(path)).
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-#### Returns
-
-`void`
-
----
-
-### resolveNavigationPath()
-
-```ts
-protected resolveNavigationPath(route): string | null;
-```
-
-Defined in: [router-bridge-base.ts:424](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L424)
-
-Resolve an actor route value to a concrete URL path for navigation.
-
-Bridges that receive raw `actor.currentRoute` values in `navigateRouter`
-can call this to normalize stateIds (with or without `#` prefix) to paths.
-Returns `null` when navigation is not possible:
-
-- unknown stateId with no route map entry
-- parameterized pattern (e.g. `/profile/:id`) — no concrete values available
-- non-path string that isn't a known stateId
-
-Route maps may store stateIds with or without the `#` prefix; both forms
-are tried automatically.
-
-#### Parameters
-
-| Parameter | Type     | Description                                                    |
-| --------- | -------- | -------------------------------------------------------------- |
-| `route`   | `string` | Raw actor route value (stateId, `#`-stateId, or concrete path) |
-
-#### Returns
-
-`string` \| `null`
-
-Concrete URL path, or `null` if navigation should be skipped
-
----
-
-### sanitizePath()
-
-```ts
-protected sanitizePath(pathname): string | null;
-```
-
-Defined in: [router-bridge-base.ts:466](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L466)
-
-Sanitize and validate a raw URL pathname received from the router.
-
-Applies the path-length cap (2048 chars), strips query strings and fragments
-that may have been included in the pathname segment, and normalises
-consecutive slashes.
-
-Implementations that bypass `syncActorFromRouter()` (e.g. when using
-framework-native reactive watchers that receive pre-parsed route objects)
-MUST call this method before passing the path to any route-map lookup.
-`syncActorFromRouter()` calls this internally, so bridges that delegate
-to it do not need to call `sanitizePath` themselves.
-
-#### Parameters
-
-| Parameter  | Type     | Description                                 |
-| ---------- | -------- | ------------------------------------------- |
-| `pathname` | `string` | Raw URL pathname from the framework router. |
-
-#### Returns
-
-`string` \| `null`
-
-Sanitized pathname, or `null` if the path is invalid / too long.
-
----
-
-### syncActorFromRouter()
-
-```ts
-protected syncActorFromRouter(pathname, search?): void;
-```
-
-Defined in: [router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L324)
-
-Sync actor state when router location changes.
-
-**Known path:** sends a `play.route` event to the actor with the matched
-stateId, params, and query. Prevents circular updates via the
-`isProcessingNavigation` flag.
-
-**Unknown/unmapped path:** does NOT send a `play.route` event (actor state
-is unchanged). Instead, actively corrects the browser URL by calling
-`navigateRouter(actor.currentRoute.get())` — keeping the URL in sync with
-actor state even when the user types an invalid path into the address bar
-or pushes one programmatically mid-session. `lastSyncedPath` is set to the
-resolved concrete path before calling `navigateRouter` so the router's own
-callback for that navigation short-circuits the echo-suppression guard and
-sends no spurious event.
-
-#### Parameters
-
-| Parameter  | Type     |
-| ---------- | -------- |
-| `pathname` | `string` |
-| `search?`  | `string` |
-
-#### Returns
-
-`void`
-
----
-
-### syncRouterFromActor()
-
-```ts
-protected syncRouterFromActor(route): void;
-```
-
-Defined in: [router-bridge-base.ts:289](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L289)
-
-Sync router location when actor route signal changes.
-
-Calls navigateRouter() for framework-specific navigation.
-
-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
-
-| Parameter | Type      |
-| --------- | --------- |
-| `route`   | `unknown` |
-
-#### Returns
-
-`void`
-
----
-
-### unwatchRouterChanges()
-
-```ts
-abstract protected unwatchRouterChanges(): void;
-```
-
-Defined in: [router-bridge-base.ts:492](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L492)
-
-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:485](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L485)
-
-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.
-
-**Implementations that call `syncActorFromRouter`** get path sanitization
-applied automatically — no extra work needed.
-
-**Implementations that bypass `syncActorFromRouter`** (e.g. `VueRouterBridge`,
-which builds the `play.route` event directly from framework-native route params)
-MUST call `this.sanitizePath(path)` and return early when it returns `null`.
-Skipping this allows oversized or malformed paths through without the length
-and content guards that protect the route-map lookup.
-
-#### Returns
-
-`void`

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.53/packages/play-router/src/router-sync.ts#L140)
+Defined in: [router-sync.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/router-sync.ts#L168)
 
 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.53/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-beta.55/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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

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

@@ -6,11 +6,11 @@
 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-beta.53/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/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
+Used by framework-router adapters that pass a
 `RouteTree` produced by `extractMachineRoutes()` rather than calling
 `createRouteMap()` directly.
 

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

@@ -6,11 +6,18 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/validate-routes.ts#L50)
+Defined in: [validate-routes.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/validate-routes.ts#L69)
 
 Detect duplicate route paths
 
-THROWS ERROR when multiple states share the same route path.
+THROWS ERROR when multiple states share the same RESOLVED full path.
+
+Detection operates on resolved full paths (after relative routes have been
+prefixed with their parent's path in `buildRouteTree`), not on raw route
+strings: two relative `"settings"` routes under different parents resolve to
+distinct full paths and are valid, while a relative route and an absolute
+route resolving to the same URL genuinely collide and must be rejected.
+Called from `buildRouteTree` once full paths are known.
 
 Rationale: URL-based routing requires one-to-one mapping between URLs and states.
 Multiple states at the same path creates ambiguity for browser navigation (back button,
@@ -19,9 +26,9 @@ conditional rendering.
 
 ## Parameters
 
-| Parameter | Type                                        | Description                          |
-| --------- | ------------------------------------------- | ------------------------------------ |
-| `routes`  | [`RouteInfo`](../interfaces/RouteInfo.md)[] | Array of extracted RouteInfo objects |
+| Parameter | Type                                                        | Description                                                         |
+| --------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
+| `routes`  | [`ResolvedRoutePath`](../interfaces/ResolvedRoutePath.md)[] | Array of route entries with resolved full paths (e.g. `RouteNode`s) |
 
 ## Returns
 
@@ -29,4 +36,4 @@ conditional rendering.
 
 ## Throws
 
-If duplicate route paths are detected
+If duplicate resolved route paths are detected

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

@@ -6,7 +6,7 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [extract-routes.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/extract-routes.ts#L93)
+Defined in: [extract-routes.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/extract-routes.ts#L89)
 
 Extract complete route tree from state machine graph
 

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

@@ -6,7 +6,7 @@
 function extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L121)
+Defined in: [router-sync.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/router-sync.ts#L149)
 
 Parse a URL search string into the plain object shape expected by
 `play.route` events.

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

@@ -6,7 +6,7 @@
 function extractRouteParams(pathname, pattern): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L101)
+Defined in: [router-sync.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/router-sync.ts#L112)
 
 Extract named path parameters from a URL using the URLPattern API.
 
@@ -16,6 +16,14 @@ For extraction via a state ID lookup, see `RouterBridgeBase.extractParams`.
 Undefined values (unmatched optional segments, e.g. `/settings` against
 `/settings/:section?`) are omitted from the returned object.
 
+The pattern is normalized with the same rules `RouteMap` uses for matching
+(hyphenated names like `:cat-id` become `:cat_id` for URLPattern), and the
+extracted group names are mapped back to the original param names, so
+`/docs/123` against `/docs/:cat-id` yields `{ "cat-id": "123" }`.
+
+Values are percent-decoded (`john%20doe` → `john doe`), matching framework
+router semantics (e.g. vue-router). Malformed sequences are kept raw.
+
 ## Parameters
 
 | Parameter  | Type     | Description                                          |

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

@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/find-route.ts#L52)
+Defined in: [find-route.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/find-route.ts#L57)
 
 Find route node by state ID
 

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

@@ -6,7 +6,7 @@
 function findRouteByPath(tree, path): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/find-route.ts#L77)
+Defined in: [find-route.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/find-route.ts#L82)
 
 Find route node by URL path
 

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

@@ -6,7 +6,7 @@
 function getNavigableRoutes(tree, stateId): RouteNode[];
 ```
 
-Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/query.ts#L22)
+Defined in: [query.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/query.ts#L64)
 
 Get all routes navigable from given state
 

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

@@ -6,7 +6,7 @@
 function getRoutableRoutes(tree): RouteNode[];
 ```
 
-Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/query.ts#L67)
+Defined in: [query.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/query.ts#L126)
 
 Get all routable routes from tree as flat array
 

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

@@ -6,7 +6,7 @@
 function getTransitionReachableRoutes(graph, stateId): string[];
 ```
 
-Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/query.ts#L113)
+Defined in: [query.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/query.ts#L177)
 
 Get routes reachable via transitions from current state
 
@@ -14,6 +14,11 @@ Uses the @statelyai/graph successor algorithm to find all states
 directly reachable via transition edges from the given state,
 then filters to those with defined routes.
 
+Returned values are the RAW `meta.route` strings from the machine — relative
+routes (e.g. `"detail"`) are NOT resolved to full paths and cannot be used as
+`tree.byPath` keys. For resolved `RouteNode`s use `getNavigableRoutes`, which
+resolves reachable states through `tree.byStateId`.
+
 ## Parameters
 
 | Parameter | Type                                                                                                                    | Description                          |
@@ -25,7 +30,7 @@ then filters to those with defined routes.
 
 `string`[]
 
-Array of route paths reachable via transitions
+Array of raw route strings reachable via transitions
 
 ## Example
 

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

@@ -6,7 +6,7 @@
 function isRouteReachable(graph, fromStateId, toStateId): boolean;
 ```
 
-Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/query.ts#L149)
+Defined in: [query.ts:204](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.55/packages/play-router/src/query.ts#L204)
 
 Check if a route is reachable from current state via transitions