@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.18

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.16/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.18/packages/play-react-router/src/react-router-bridge.ts#L28)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -25,15 +25,15 @@ 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.16/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.18/packages/play-react-router/src/react-router-bridge.ts#L31)
 
 #### Parameters
 
-| Parameter  | Type                                                                                                                                                                                          |
-| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `router`   | `Router`                                                                                                                                                                                      |
-| `actor`    | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)\> & [`Routable`](../../play-actor/interfaces/Routable.md) |
-| `routeMap` | [`RouteMap`](RouteMap.md)                                                                                                                                                                     |
+| Parameter  | Type                                                                                                                                                                                                                                                             |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `router`   | `Router`                                                                                                                                                                                                                                                         |
+| `actor`    | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) |
+| `routeMap` | [`RouteMap`](RouteMap.md)                                                                                                                                                                                                                                        |
 
 #### Returns
 
@@ -45,17 +45,17 @@ Defined in: [play-react-router/src/react-router-bridge.ts:31](https://gitlab.com
 
 ## Properties
 
-| Property                                                              | Modifier    | Type                                                                                                                                                                                          | 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)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | Actor with currentRoute signal and send method        | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | play-router/dist/router-bridge-base.d.ts:55 |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                     | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | play-router/dist/router-bridge-base.d.ts:61 |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                     | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | play-router/dist/router-bridge-base.d.ts:60 |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                     | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | play-router/dist/router-bridge-base.d.ts:63 |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string`                                                                                                                                                                                      | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | play-router/dist/router-bridge-base.d.ts:62 |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                      | Bidirectional route map for stateId ↔ path resolution | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | play-router/dist/router-bridge-base.d.ts:56 |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                             | -                                                     | -                                                                                                                                                                             | play-router/dist/router-bridge-base.d.ts:58 |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                             | -                                                     | -                                                                                                                                                                             | play-router/dist/router-bridge-base.d.ts:57 |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`Watcher`](../../play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md) \| `null`                                                                                           | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | play-router/dist/router-bridge-base.d.ts:64 |
+| Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | 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) | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | play-router/dist/router-bridge-base.d.ts:73 |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | play-router/dist/router-bridge-base.d.ts:79 |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | play-router/dist/router-bridge-base.d.ts:78 |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | play-router/dist/router-bridge-base.d.ts:81 |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | play-router/dist/router-bridge-base.d.ts:80 |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | 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/dist/router-bridge-base.d.ts:74 |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | -                                                                                                                                                                                                | -                                                                                                                                                                             | play-router/dist/router-bridge-base.d.ts:76 |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | -                                                                                                                                                                                                | -                                                                                                                                                                             | play-router/dist/router-bridge-base.d.ts:75 |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | play-router/dist/router-bridge-base.d.ts:82 |
 
 ## 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/dist/router-bridge-base.d.ts:81
+Defined in: play-router/dist/router-bridge-base.d.ts:99
 
 Connect the router bridge to the Actor.
 
@@ -88,7 +88,7 @@ starts watching router changes (framework-specific).
 disconnect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:87
+Defined in: play-router/dist/router-bridge-base.d.ts:105
 
 Disconnect the router bridge from the Actor.
 
@@ -110,7 +110,7 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:134
+Defined in: play-router/dist/router-bridge-base.d.ts:132
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -121,10 +121,10 @@ works, params will be empty).
 
 #### Parameters
 
-| Parameter  | Type     | Description                                       |
-| ---------- | -------- | ------------------------------------------------- |
-| `pathname` | `string` | The actual URL path (e.g., '/profile/john')       |
-| `stateId`  | `string` | The matched state ID for looking up route pattern |
+| Parameter  | Type     | Description                                           |
+| ---------- | -------- | ----------------------------------------------------- |
+| `pathname` | `string` | The actual URL path (e.g., '/profile/john')           |
+| `stateId`  | `string` | The matched state ID for looking up the route pattern |
 
 #### Returns
 
@@ -144,7 +144,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:141
+Defined in: play-router/dist/router-bridge-base.d.ts:139
 
 Extract query parameters from URL search string.
 
@@ -172,7 +172,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.16/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.18/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
@@ -195,7 +195,7 @@ the page on /about would leave the actor in its default "home" state.
 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.16/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.18/packages/play-react-router/src/react-router-bridge.ts#L39)
 
 Navigate the framework router to the given path.
 
@@ -224,7 +224,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:101
+Defined in: play-router/dist/router-bridge-base.d.ts:119
 
 Sync actor state when router location changes.
 
@@ -254,7 +254,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:94
+Defined in: play-router/dist/router-bridge-base.d.ts:112
 
 Sync router location when actor route signal changes.
 
@@ -283,7 +283,7 @@ Prevents circular updates via isProcessingNavigation flag.
 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.16/packages/play-react-router/src/react-router-bridge.ts#L59)
+Defined in: [play-react-router/src/react-router-bridge.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/react-router-bridge.ts#L59)
 
 Stop watching for router location changes.
 
@@ -305,7 +305,7 @@ 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.16/packages/play-react-router/src/react-router-bridge.ts#L53)
+Defined in: [play-react-router/src/react-router-bridge.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/react-router-bridge.ts#L53)
 
 Start watching for router location changes.
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/route-map.ts#L54)
+Defined in: [play-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/route-map.ts#L54)
 
 Bidirectional route mapper for React Router.
 
@@ -40,12 +40,12 @@ routeMap.getPathByStateId("home"); // "/"
 new RouteMap(mappings): RouteMap;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:81
+Defined in: play-router/dist/base-route-map.d.ts:82
 
 Build a route map from an array of state ID ↔ path mappings.
 
 Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `RegExp` and grouped into first-segment
+Parameterized paths are compiled to `URLPattern` and grouped into first-segment
 buckets for efficient candidate selection.
 
 #### Parameters
@@ -70,7 +70,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:111
+Defined in: play-router/dist/base-route-map.d.ts:112
 
 Look up the path pattern registered for a state ID.
 
@@ -105,7 +105,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:98
+Defined in: play-router/dist/base-route-map.d.ts:99
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -3,16 +3,22 @@
 # Function: PlayRouterProvider()
 
 ```ts
-function PlayRouterProvider(__namedParameters): Element;
+function PlayRouterProvider<TActor>(__namedParameters): Element;
 ```
 
-Defined in: [play-react-router/src/play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/play-router-provider.tsx#L20)
+Defined in: [play-react-router/src/play-router-provider.tsx:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/play-router-provider.tsx#L21)
+
+## Type Parameters
+
+| Type Parameter                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TActor` _extends_ [`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) & [`Viewable`](../../play-actor/interfaces/Viewable.md) |
 
 ## Parameters
 
-| Parameter           | Type                                                                  |
-| ------------------- | --------------------------------------------------------------------- |
-| `__namedParameters` | [`PlayRouterProviderProps`](../interfaces/PlayRouterProviderProps.md) |
+| Parameter           | Type                                                                              |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `__namedParameters` | [`PlayRouterProviderProps`](../interfaces/PlayRouterProviderProps.md)\<`TActor`\> |
 
 ## Returns
 

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

@@ -6,7 +6,7 @@
 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.16/packages/play-react-router/src/route-map.ts#L73)
+Defined in: [play-react-router/src/route-map.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/route-map.ts#L73)
 
 Create RouteMap from RouteTree
 

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

@@ -1,14 +1,20 @@
 [Documentation](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProviderProps
 
-# Interface: PlayRouterProviderProps
+# Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/play-router-provider.tsx#L10)
+Defined in: [play-react-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/play-router-provider.tsx#L10)
+
+## Type Parameters
+
+| Type Parameter                                                                                                                                                                                                                                                           | Default type                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TActor` _extends_ [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)\> & [`Routable`](../../play-actor/interfaces/Routable.md) & [`Viewable`](../../play-actor/interfaces/Viewable.md) | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)\> & [`Routable`](../../play-actor/interfaces/Routable.md) & [`Viewable`](../../play-actor/interfaces/Viewable.md) |
 
 ## Properties
 
-| Property                                  | Type                                                                                                                                                                                                                                                  | Defined in                                                                                                                                                                        |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)\> & [`Routable`](../../play-actor/interfaces/Routable.md) & [`Viewable`](../../play-actor/interfaces/Viewable.md) | [play-react-router/src/play-router-provider.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/play-router-provider.tsx#L11) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`                                                                                                                                                                                                                    | [play-react-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/play-router-provider.tsx#L14) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                  | [play-react-router/src/play-router-provider.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/play-router-provider.tsx#L13) |
-| <a id="property-router"></a> `router`     | `Router`                                                                                                                                                                                                                                              | [play-react-router/src/play-router-provider.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/play-router-provider.tsx#L12) |
+| Property                                  | Type                                 | Description                                                                 | Defined in                                                                                                                                                                        |
+| ----------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | -                                                                           | [play-react-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/play-router-provider.tsx#L14) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in. | [play-react-router/src/play-router-provider.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/play-router-provider.tsx#L18) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | -                                                                           | [play-react-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/play-router-provider.tsx#L16) |
+| <a id="property-router"></a> `router`     | `Router`                             | -                                                                           | [play-react-router/src/play-router-provider.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/play-router-provider.tsx#L15) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/route-map.ts#L22)
+Defined in: [play-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/route-map.ts#L22)
 
 Mapping between state machine state ID and router path.
 
@@ -13,5 +13,5 @@ Fields are `readonly` — entries are immutable once passed to `RouteMap`.
 
 | Property                                | Modifier   | Type     | Description                                                          | Defined in                                                                                                                                                |
 | --------------------------------------- | ---------- | -------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | Router path with optional parameters (e.g., `"/settings/:section?"`) | [play-react-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/route-map.ts#L26) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State ID from state machine (e.g., `"home"`, `"settings.profile"`)   | [play-react-router/src/route-map.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-react-router/src/route-map.ts#L24) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | Router path with optional parameters (e.g., `"/settings/:section?"`) | [play-react-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/route-map.ts#L26) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State ID from state machine (e.g., `"home"`, `"settings.profile"`)   | [play-react-router/src/route-map.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-react-router/src/route-map.ts#L24) |

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

@@ -14,6 +14,8 @@ It also exports `RouterBridgeBase`, the shared base class used by framework adap
 
 `RouterBridgeBase` is the policy point; framework adapters are thin ports that implement only framework-specific navigate/subscribe/unsubscribe behavior.
 
+The low-level `connectRouter()` path now uses the same router-to-actor event builder and route-map match helper as `RouterBridgeBase`, so pathname sanitization, state-id normalization, param extraction, and query extraction stay aligned across vanilla and framework adapters.
+
 Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
 
 - **Actor Authority (INV-01):** Routes derive from machine definitions, not external configuration
@@ -180,6 +182,17 @@ Bridge teardown must be explicit and deterministic:
 - `disconnect`/`dispose` must unwatch signal subscriptions and unhook router listeners.
 - Do not rely on GC-only cleanup guidance.
 - Infrastructure remains passive: bridges observe and forward intents, actors decide validity.
+- `createBrowserHistory().destroy()` is idempotent and restores shared `window.history` patches only after the last wrapper for that window is removed.
+
+## Diagnostics
+
+Router infrastructure reports runtime failures through `PlayDiagnostics` from `@xmachines/play`.
+
+- Default behavior uses `consoleDiagnostics`.
+- Messages follow a stable `[scope:code] message` format.
+- Example: `[RouterBridgeBase:PLAY_ROUTER_SYNC_FAILED] Failed to sync actor state from router location.`
+
+This keeps router errors observable while letting applications swap in their own diagnostics implementation upstream.
 
 ## API Reference
 
@@ -428,6 +441,43 @@ meta: {
 
 **Parameter substitution:** Values extracted from context or event params (handled by play-xstate adapter).
 
+## Error Handling
+
+All runtime errors thrown by this package extend `PlayError` from `@xmachines/play` and
+are exported from the `./errors` subpath:
+
+```typescript
+import {
+	RouterSyncError,
+	URLPatternUnavailableError,
+	InvalidRoutePatternError,
+} from "@xmachines/play-router/errors";
+```
+
+| Class                        | Code                                    | When thrown                                                    |
+| ---------------------------- | --------------------------------------- | -------------------------------------------------------------- |
+| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` fails to send a `play.route` event     |
+| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | `createRouteMap()` called before URLPattern polyfill is loaded |
+| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern string is rejected by URLPattern constructor   |
+
+`InvalidRoutePatternError` carries a `pattern: string` field with the offending pattern.
+
+```typescript
+import { PlayError } from "@xmachines/play";
+import { RouterSyncError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof RouterSyncError) {
+		// err.cause — the original error that triggered the sync failure
+		monitoringService.record(err);
+	} else if (err instanceof PlayError) {
+		console.error(`[${err.scope}:${err.code}] ${err.message}`);
+	}
+}
+```
+
 ## Architecture
 
 This package enables **Actor Authority (INV-01)**:
@@ -475,6 +525,7 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [RouteObject](interfaces/RouteObject.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 - [RouteTree](interfaces/RouteTree.md)
+- [RouteWatcherHandle](interfaces/RouteWatcherHandle.md)
 - [StateVisit](interfaces/StateVisit.md)
 - [VanillaRouter](interfaces/VanillaRouter.md)
 

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

@@ -2,7 +2,7 @@
 
 # Class: BaseRouteMap
 
-Defined in: [base-route-map.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/base-route-map.ts#L70)
+Defined in: [base-route-map.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/base-route-map.ts#L106)
 
 Shared bidirectional route map base class.
 
@@ -12,7 +12,7 @@ own and inherit the full public API from here.
 **Lookup strategy:**
 
 - Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
+- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
   of routes sharing the same first path segment
 - Results are cached after the first match
 
@@ -57,12 +57,12 @@ map.getPathByStateId("missing"); // null
 new BaseRouteMap(mappings): BaseRouteMap;
 ```
 
-Defined in: [base-route-map.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/base-route-map.ts#L86)
+Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
 Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `RegExp` and grouped into first-segment
+Parameterized paths are compiled to `URLPattern` and grouped into first-segment
 buckets for efficient candidate selection.
 
 #### Parameters
@@ -83,7 +83,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/base-route-map.ts#L164)
+Defined in: [base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/base-route-map.ts#L210)
 
 Look up the path pattern registered for a state ID.
 
@@ -114,7 +114,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-router/src/base-route-map.ts#L130)
+Defined in: [base-route-map.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.18/packages/play-router/src/base-route-map.ts#L175)
 
 Resolve a URL path to its mapped state ID.