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

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.54/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.54/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` | -                                                                                                                   |
 
@@ -49,15 +49,15 @@ Defined in: [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-
 
 | 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) |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../interfaces/RoutableActor.md)                     | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L124) |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L98)   |
+| <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:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L111) |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                    | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L100) |
+| <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. `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.                                                                          | [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L125) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L127) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L126) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null` | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L112) |
 
 ## Methods
 
@@ -67,7 +67,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.54/packages/play-router/src/router-bridge-base.ts#L151)
 
 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: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.54/packages/play-router/src/router-bridge-base.ts#L256)
 
 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:402](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L402)
+Defined in: [router-bridge-base.ts:423](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L423)
 
 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:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L439)
+Defined in: [router-bridge-base.ts:480](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L480)
 
 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:512](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L512)
+Defined in: [router-bridge-base.ts:559](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L559)
 
 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:529](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L529)
+Defined in: [router-bridge-base.ts:576](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L576)
 
 Return the router's current search string at connect() time.
 
@@ -237,10 +237,16 @@ URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
 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)
+Defined in: [router-bridge-base.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L495)
 
 Must trigger the framework router's navigation (e.g., router.navigate(path)).
 
+Contract: `path` is always a RESOLVED concrete URL path (e.g. `"/home"`).
+The base class resolves actor route values (stateIds like `"#home"`,
+parameterized patterns) via `resolveNavigationPath()` before calling this
+method and skips the push entirely when resolution fails — implementations
+must NOT re-resolve and can push the value as-is.
+
 #### Parameters
 
 | Parameter | Type     |
@@ -259,7 +265,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 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)
+Defined in: [router-bridge-base.ts:447](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L447)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -268,11 +274,13 @@ 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
+- parameterized or wildcard pattern (e.g. `/profile/:id`, `/docs/*`) — no
+  concrete values available to build a real URL
 - non-path string that isn't a known stateId
 
-Route maps may store stateIds with or without the `#` prefix; both forms
-are tried automatically.
+StateId lookups try both the `"#stateId"` and bare `"stateId"` forms
+automatically (via `lookupPathByStateId`), so custom route maps keyed on
+only one form still resolve.
 
 #### Parameters
 
@@ -294,7 +302,7 @@ Concrete URL path, or `null` if navigation should be skipped
 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)
+Defined in: [router-bridge-base.ts:513](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L513)
 
 Sanitize and validate a raw URL pathname received from the router.
 
@@ -328,7 +336,7 @@ Sanitized pathname, or `null` if the path is invalid / too long.
 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)
+Defined in: [router-bridge-base.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L347)
 
 Sync actor state when router location changes.
 
@@ -364,17 +372,22 @@ sends no spurious event.
 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)
+Defined in: [router-bridge-base.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L302)
 
 Sync router location when actor route signal changes.
 
-Calls navigateRouter() for framework-specific navigation.
+Resolves the actor route to a concrete URL path and calls navigateRouter()
+for framework-specific navigation. When the route cannot be resolved
+(unknown stateId, parameterized pattern with no concrete values) the push
+is skipped entirely — `navigateRouter` is never called with a raw stateId
+or pattern.
 
 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.
+actor — is handled entirely by `lastSyncedPath`: it is set to the resolved
+path 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.
@@ -397,7 +410,7 @@ no event regardless of whether the callback fires synchronously or asynchronousl
 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)
+Defined in: [router-bridge-base.ts:539](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L539)
 
 Stop watching for router location changes.
 
@@ -415,7 +428,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 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)
+Defined in: [router-bridge-base.ts:532](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L532)
 
 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.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.54/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.54/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.54/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.54/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.54/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`[] | 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.54/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.54/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.54/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.54/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.54/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.54/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.54/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.54/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.54/packages/play-router/src/query.ts#L204)
 
 Check if a route is reachable from current state via transitions
 

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

@@ -6,7 +6,7 @@
 function machineToGraph(machine): MachineGraph;
 ```
 
-Defined in: [machine-to-graph.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/machine-to-graph.ts#L71)
+Defined in: [machine-to-graph.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/machine-to-graph.ts#L71)
 
 ## Parameters
 

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

@@ -6,7 +6,7 @@
 function routeExists(tree, path): boolean;
 ```
 
-Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/query.ts#L89)
+Defined in: [query.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/query.ts#L148)
 
 Validate route path exists in tree
 

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

@@ -6,7 +6,7 @@
 function sanitizePathname(pathname): string | null;
 ```
 
-Defined in: [router-sync.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L69)
+Defined in: [router-sync.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-sync.ts#L72)
 
 Normalize a pathname before route-map lookup.
 

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

@@ -6,7 +6,7 @@
 function validateRouteFormat(routePath, stateId): void;
 ```
 
-Defined in: [validate-routes.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/validate-routes.ts#L15)
+Defined in: [validate-routes.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/validate-routes.ts#L27)
 
 Validate route path format
 

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

@@ -6,7 +6,7 @@
 function validateStateExists(stateId, stateIds): void;
 ```
 
-Defined in: [validate-routes.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/validate-routes.ts#L31)
+Defined in: [validate-routes.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/validate-routes.ts#L43)
 
 Validate state exists in state ID set
 

package/api/@xmachines/play-router/interfaces/BuildPlayRouteEventOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: BuildPlayRouteEventOptions
 
-Defined in: [router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L14)
+Defined in: [router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-sync.ts#L17)
 
 ## Properties
 
 | Property                                  | Type                                                   | Defined in                                                                                                                        |
 | ----------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match`       | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L17) |
-| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L15) |
-| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-sync.ts#L16) |
+| <a id="property-match"></a> `match`       | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-sync.ts#L20) |
+| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-sync.ts#L18) |
+| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-sync.ts#L19) |

package/api/@xmachines/play-router/interfaces/LocationLike.md

@@ -2,7 +2,7 @@
 
 # Interface: LocationLike
 
-Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L414)
+Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L414)
 
 Minimal location interface required by adapters that read the current URL at
 `connect()` time. Injectable for SSR and testing — pass a mock instead of the
@@ -23,5 +23,5 @@ connectRouter({ actor, routeMap, location: mockLoc });
 
 | Property                                  | Modifier   | Type     | Defined in                                                                                                              |
 | ----------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [types.ts:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L415) |
-| <a id="property-search"></a> `search`     | `readonly` | `string` | [types.ts:416](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L416) |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [types.ts:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L415) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [types.ts:416](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L416) |

package/api/@xmachines/play-router/interfaces/MachineEdgeData.md

@@ -2,7 +2,7 @@
 
 # Interface: MachineEdgeData
 
-Defined in: [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L24)
+Defined in: [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L24)
 
 Data attached to each edge in the machine graph representation.
 Captures transition event and guard information.
@@ -11,5 +11,5 @@ Captures transition event and guard information.
 
 | Property                                     | Type     | Description                                  | Defined in                                                                                                            |
 | -------------------------------------------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L26) |
-| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L28) |
+| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L26) |
+| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L28) |