@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

package/api/@xmachines/play-react/interfaces/PlayErrorBoundaryProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayErrorBoundaryProps
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L14)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L14)
 
 Props for PlayErrorBoundary
 
@@ -10,6 +10,6 @@ Props for PlayErrorBoundary
 
 | Property                                   | Type                        | Description                                                                             | Defined in                                                                                                                                                             |
 | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-children"></a> `children`  | `ReactNode`                 | Child components to render                                                              | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
-| <a id="property-fallback"></a> `fallback?` | `ReactNode`                 | Fallback UI to render when a child component throws. Defaults to null.                  | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
-| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void` | Optional error handler callback — forwards errors to observability tools (Sentry, etc.) | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L20) |
+| <a id="property-children"></a> `children`  | `ReactNode`                 | Child components to render                                                              | [packages/play-react/src/PlayErrorBoundary.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L18) |
+| <a id="property-fallback"></a> `fallback?` | `ReactNode`                 | Fallback UI to render when a child component throws. Defaults to null.                  | [packages/play-react/src/PlayErrorBoundary.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L16) |
+| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void` | Optional error handler callback — forwards errors to observability tools (Sentry, etc.) | [packages/play-react/src/PlayErrorBoundary.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L20) |

package/api/@xmachines/play-react/interfaces/PlayErrorBoundaryState.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayErrorBoundaryState
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L28)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L28)
 
 Internal state shape for PlayErrorBoundary
 
@@ -10,5 +10,5 @@ Internal state shape for PlayErrorBoundary
 
 | Property                                  | Type              | Defined in                                                                                                                                                             |
 | ----------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-error"></a> `error`       | `Error` \| `null` | [packages/play-react/src/PlayErrorBoundary.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L30) |
-| <a id="property-haserror"></a> `hasError` | `boolean`         | [packages/play-react/src/PlayErrorBoundary.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayErrorBoundary.tsx#L29) |
+| <a id="property-error"></a> `error`       | `Error` \| `null` | [packages/play-react/src/PlayErrorBoundary.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L30) |
+| <a id="property-haserror"></a> `hasError` | `boolean`         | [packages/play-react/src/PlayErrorBoundary.tsx:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayErrorBoundary.tsx#L29) |

package/api/@xmachines/play-react/interfaces/PlayRendererProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRendererProps\<TLogic\>
 
-Defined in: [packages/play-react/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L33)
+Defined in: [packages/play-react/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L33)
 
 Props for PlayRenderer component
 
@@ -16,9 +16,9 @@ Props for PlayRenderer component
 
 | Property                                   | Type                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                                                   |
 | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actions"></a> `actions?`   | `object`                                                                                                                                                                                            | Maps json-render action names to XState event type strings. Values are constrained to `EventFromLogic<TLogic>["type"]` — passing a non-existent event type string is a compile error when TLogic is specified.                                                                                                      | [packages/play-react/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L70) |
-| <a id="property-actor"></a> `actor`        | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                               | [packages/play-react/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L35) |
-| <a id="property-fallback"></a> `fallback?` | `ReactNode`                                                                                                                                                                                         | Optional component shown when currentView is null                                                                                                                                                                                                                                                                   | [packages/play-react/src/types.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L51) |
-| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void`                                                                                                                                                                         | Optional callback invoked when a catalog component throws during render. Receives the error and React ErrorInfo — use to forward to Sentry, Datadog, etc.                                                                                                                                                           | [packages/play-react/src/types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L63) |
-| <a id="property-registry"></a> `registry`  | `ComponentRegistry`                                                                                                                                                                                 | ComponentRegistry from defineRegistry() in @json-render/react                                                                                                                                                                                                                                                       | [packages/play-react/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L38) |
-| <a id="property-store"></a> `store?`       | `StateStore`                                                                                                                                                                                        | Optional external StateStore (e.g. from @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored and the store is the single source of truth for UI state. When omitted, a fresh @xstate/store atom is created internally per view transition, seeded from spec.state. | [packages/play-react/src/types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/types.ts#L48) |
+| <a id="property-actions"></a> `actions?`   | `object`                                                                                                                                                                                            | Maps json-render action names to XState event type strings. Values are constrained to `EventFromLogic<TLogic>["type"]` — passing a non-existent event type string is a compile error when TLogic is specified.                                                                                                      | [packages/play-react/src/types.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L70) |
+| <a id="property-actor"></a> `actor`        | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                               | [packages/play-react/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L35) |
+| <a id="property-fallback"></a> `fallback?` | `ReactNode`                                                                                                                                                                                         | Optional component shown when currentView is null                                                                                                                                                                                                                                                                   | [packages/play-react/src/types.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L51) |
+| <a id="property-onerror"></a> `onError?`   | (`error`, `info`) => `void`                                                                                                                                                                         | Optional callback invoked when a catalog component throws during render. Receives the error and React ErrorInfo — use to forward to Sentry, Datadog, etc.                                                                                                                                                           | [packages/play-react/src/types.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L63) |
+| <a id="property-registry"></a> `registry`  | `ComponentRegistry`                                                                                                                                                                                 | ComponentRegistry from defineRegistry() in @json-render/react                                                                                                                                                                                                                                                       | [packages/play-react/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L38) |
+| <a id="property-store"></a> `store?`       | `StateStore`                                                                                                                                                                                        | Optional external StateStore (e.g. from @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored and the store is the single source of truth for UI state. When omitted, a fresh @xstate/store atom is created internally per view transition, seeded from spec.state. | [packages/play-react/src/types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/types.ts#L48) |

package/api/@xmachines/play-react/type-aliases/ComponentFn.md

@@ -6,6 +6,8 @@
 type ComponentFn<C, K> = (ctx) => ReactNode;
 ```
 
+Defined in: `@json-render/react`
+
 Component render function type for React
 
 ## Type Parameters

package/api/@xmachines/play-react/type-aliases/PlayActor.md

@@ -6,4 +6,4 @@
 type PlayActor = AbstractActor<AnyActorLogic>;
 ```
 
-Defined in: [packages/play-react/src/useActor.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/useActor.ts#L26)
+Defined in: [packages/play-react/src/useActor.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/useActor.ts#L26)

package/api/@xmachines/play-react/variables/PlayRenderer.md

@@ -6,7 +6,7 @@
 const PlayRenderer: React.FC<PlayRendererProps>;
 ```
 
-Defined in: [packages/play-react/src/PlayRenderer.tsx:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react/src/PlayRenderer.tsx#L65)
+Defined in: [packages/play-react/src/PlayRenderer.tsx:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react/src/PlayRenderer.tsx#L65)
 
 Main renderer component that subscribes to actor signals and renders UI
 via @json-render/react Renderer.

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

@@ -83,7 +83,7 @@ Responsibilities:
 
 - Watch React Router location updates and sync actor via `play.route`
 - Observe actor route changes and navigate router when state changes
-- Handle initial URL sync on cold load/deep links
+- Handle initial URL sync on cold load/deep links (pathname **and** query string are forwarded)
 
 ### `PlayRouterProvider`
 
@@ -120,6 +120,10 @@ function createRouteMapFromTree(routeTree: RouteTree): RouteMap
 
 `getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
 
+`createRouteMapFromTree` uses `node.fullPath` (the fully resolved absolute path) for all
+route entries. This is correct for both flat routes (e.g. `"/login"`) and nested relative
+routes (e.g. `meta.route: "overview"` under `"/dashboard"` resolves to `"/dashboard/overview"`).
+
 Construct directly when you have static mappings:
 
 ```ts

package/api/@xmachines/play-react-router/classes/ReactRouterBridge.md

@@ -2,7 +2,7 @@
 
 # Class: ReactRouterBridge
 
-Defined in: [play-react-router/src/react-router-bridge.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/react-router-bridge.ts#L28)
+Defined in: [play-react-router/src/react-router-bridge.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L28)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -25,7 +25,7 @@ new ReactRouterBridge(
    routeMap): ReactRouterBridge;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/react-router-bridge.ts#L31)
+Defined in: [play-react-router/src/react-router-bridge.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L31)
 
 #### Parameters
 
@@ -47,15 +47,15 @@ Defined in: [play-react-router/src/react-router-bridge.ts:31](https://gitlab.com
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L102) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L90)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L89)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L92)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L91)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L103) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L105) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L93)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L89)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L102) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L101) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L90)   |
 
 ## Methods
 
@@ -65,7 +65,7 @@ Defined in: [play-react-router/src/react-router-bridge.ts:31](https://gitlab.com
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L129)
+Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L126)
 
 Connect the router bridge to the Actor.
 
@@ -97,7 +97,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L197)
+Defined in: [play-router/src/router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L209)
 
 Disconnect the router bridge from the Actor.
 
@@ -119,14 +119,14 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:300](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L300)
+Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L318)
 
 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).
+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
 
@@ -139,7 +139,11 @@ works, params will be empty).
 
 `Record`\<`string`, `string`\>
 
-Extracted path parameters, or empty object if URLPattern is unavailable or no match
+Extracted path parameters, or empty object if no match
+
+#### Throws
+
+When URLPattern is absent and the route is parameterized
 
 #### Inherited from
 
@@ -153,7 +157,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:321](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L321)
+Defined in: [play-router/src/router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L355)
 
 Extract query parameters from URL search string.
 
@@ -181,7 +185,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/react-router-bridge.ts#L49)
+Defined in: [play-react-router/src/react-router-bridge.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L49)
 
 Return the router's current pathname so connect() can sync the actor to
 the URL on initial load. router.subscribe() only fires on future navigations
@@ -198,13 +202,37 @@ the page on /about would leave the actor in its default "home" state.
 
 ---
 
+### getInitialRouterSearch()
+
+```ts
+protected getInitialRouterSearch(): string | undefined;
+```
+
+Defined in: [play-react-router/src/react-router-bridge.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L60)
+
+Return the initial URL search string for query-param forwarding on `connect()`.
+
+Reads from `router.state.location.search` — the same source used by
+`getInitialRouterPath()`. An empty string (no query params) returns `undefined`
+so `syncActorFromRouter` produces `query: {}` rather than parsing an empty string.
+
+#### Returns
+
+`string` \| `undefined`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`getInitialRouterSearch`](../../play-router/classes/RouterBridgeBase.md#getinitialroutersearch)
+
+---
+
 ### navigateRouter()
 
 ```ts
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/react-router-bridge.ts#L39)
+Defined in: [play-react-router/src/react-router-bridge.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L39)
 
 Navigate the framework router to the given path.
 
@@ -227,13 +255,52 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 
 ---
 
+### resolveNavigationPath()
+
+```ts
+protected resolveNavigationPath(route): string | null;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L340)
+
+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
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`resolveNavigationPath`](../../play-router/classes/RouterBridgeBase.md#resolvenavigationpath)
+
+---
+
 ### syncActorFromRouter()
 
 ```ts
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L260)
 
 Sync actor state when router location changes.
 
@@ -263,7 +330,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L228)
+Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L240)
 
 Sync router location when actor route signal changes.
 
@@ -296,7 +363,7 @@ suppressed as circular echoes.
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/react-router-bridge.ts#L59)
+Defined in: [play-react-router/src/react-router-bridge.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L70)
 
 Stop watching for router location changes.
 
@@ -318,13 +385,23 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/react-router-bridge.ts#L53)
+Defined in: [play-react-router/src/react-router-bridge.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/react-router-bridge.ts#L64)
 
 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 `sanitizePathname`
+applied automatically — no extra work needed.
+
+**Implementations that bypass `syncActorFromRouter`** (e.g. `VueRouterBridge`,
+which builds the `play.route` event directly from `afterEach` params) MUST
+apply `sanitizePathname(path)` manually before processing the path. Skipping
+this allows oversized or malformed paths through without the length/content
+guards that protect the route-map lookup. Import `sanitizePathname` from
+`@xmachines/play-router`.
+
 #### Returns
 
 `void`

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

@@ -2,45 +2,25 @@
 
 # Class: RouteMap
 
-Defined in: [play-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/route-map.ts#L54)
+Defined in: [play-react-router/src/route-map.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/route-map.ts#L12)
 
 Bidirectional route mapper for React Router.
 
-Extends [BaseRouteMap](../../play-router/classes/BaseRouteMap.md) — all matching logic lives there.
-This class exists to provide a React Router-specific type name and to allow
-future adapter-specific extensions without breaking the shared base.
-
-**Inherited API:**
-
-- `getStateIdByPath(path): string | null` — path → state ID
-- `getPathByStateId(stateId): string | null` — state ID → path pattern
-
-## Example
-
-```typescript
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
-
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-```
+Alias for [BaseRouteMap](../../play-dom-router/interfaces/RouteMap.md) from `@xmachines/play-router`.
 
 ## Extends
 
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+- [`RouteMap`](../../play-dom-router/interfaces/RouteMap.md)
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new RouteMap(mappings): RouteMap;
+new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L118)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -50,9 +30,11 @@ buckets for efficient candidate selection.
 
 #### Parameters
 
-| Parameter  | Type                                                                     | Description                                                                                                       |
-| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+| 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
 
@@ -60,7 +42,9 @@ buckets for efficient candidate selection.
 
 #### Inherited from
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+```ts
+BaseRouteMap.constructor;
+```
 
 ## Methods
 
@@ -70,7 +54,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L202)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -95,7 +79,7 @@ map.getPathByStateId("missing"); // null
 
 #### Inherited from
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
+[`RouteMap`](../../play-dom-router/interfaces/RouteMap.md).[`getPathByStateId`](../../play-dom-router/interfaces/RouteMap.md#getpathbystateid)
 
 ---
 
@@ -105,7 +89,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L167)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 
@@ -134,4 +118,4 @@ map.getStateIdByPath("/unknown"); // null
 
 #### Inherited from
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)
+[`RouteMap`](../../play-dom-router/interfaces/RouteMap.md).[`getStateIdByPath`](../../play-dom-router/interfaces/RouteMap.md#getstateidbypath)

package/api/@xmachines/play-react-router/functions/PlayRouterProvider.md

@@ -6,7 +6,14 @@
 function PlayRouterProvider<TActor>(__namedParameters): Element;
 ```
 
-Defined in: [play-react-router/src/play-router-provider.tsx:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/play-router-provider.tsx#L21)
+Defined in: [play-react-router/src/play-router-provider.tsx:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-react-router/src/play-router-provider.tsx#L47)
+
+Connects a `PlayerActor` to React Router, keeping actor state and browser URL
+in sync bidirectionally.
+
+The bridge is created once on mount and torn down on unmount. It is also
+rebuilt if `actor`, `router`, or `routeMap` change identity — so all three
+props must be **stable references** (created outside JSX or memoized).
 
 ## Type Parameters
 

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

@@ -6,30 +6,40 @@
 function createRouteMapFromTree(routeTree): RouteMap;
 ```
 
-Defined in: [play-react-router/src/route-map.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/route-map.ts#L73)
+Defined in: [play-router/src/create-route-map-from-tree.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map-from-tree.ts#L31)
 
-Create RouteMap from RouteTree
+Create a `BaseRouteMap` from a `RouteTree` node structure.
 
-Converts XMachines route tree to RouteMap for use with router adapters.
+Used by framework-router adapters (React Router, TanStack Router) that pass a
+`RouteTree` produced by `extractMachineRoutes()` rather than calling
+`createRouteMapFromMachine()` 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 `BaseRouteMap` needs for browser URL matching. This matches the
+behaviour of `createRouteMapFromMachine`, which also uses `node.fullPath`.
 
 ## Parameters
 
-| Parameter   | Type                                                     | Description                            |
-| ----------- | -------------------------------------------------------- | -------------------------------------- |
-| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | Route tree from extractMachineRoutes() |
+| Parameter   | Type                                                     | Description                                            |
+| ----------- | -------------------------------------------------------- | ------------------------------------------------------ |
+| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | A `RouteTree` as returned by `extractMachineRoutes()`. |
 
 ## Returns
 
-[`RouteMap`](../classes/RouteMap.md)
+[`RouteMap`](../../play-dom-router/interfaces/RouteMap.md)
 
-RouteMap instance
+A `BaseRouteMap` for use with any `RouterBridgeBase`-based adapter.
 
 ## Example
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-react-router";
+// Preferred — single call for XState machines:
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+const routeMap = createRouteMapFromMachine(machine);
 
+// Equivalent two-step form used by framework adapters:
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
 const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
 ```