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

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/play-router-provider.tsx#L26)
+Defined in: [play-react-router/src/play-router-provider.tsx:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/play-router-provider.tsx#L26)
 
 Props for the React Router `PlayRouterProvider`.
 
@@ -24,7 +24,7 @@ See `PlayRouterProviderBaseProps` for the stable-reference requirements on
 
 | Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Inherited from                                                                                                                 | Defined in                                                                                                                                                                                      |
 | ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
-| <a id="property-router"></a> `router`     | `Router`                             | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L42) |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
+| <a id="property-router"></a> `router`     | `Router`                             | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/create-play-router-provider.tsx#L42) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/create-route-map.ts#L9)
 
 Options for `createRouteMap` and `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ Options for `createRouteMap` and `createRouteMapFromTree`.
 
 | Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                  |
 | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map.ts#L20) |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L51)
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L51)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
 | --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L55) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L53) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L53) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L341)
+Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/types.ts#L341)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L357)
+Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/types.ts#L357)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L373)
+Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/types.ts#L373)
 
 Disconnect the router bridge from the Actor
 

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

@@ -6,7 +6,7 @@
 type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
 ```
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/create-play-router-provider.tsx#L20)
+Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/create-play-router-provider.tsx#L20)
 
 Constructor shape a bridge class must satisfy to be used with
 `createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.

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

@@ -6,7 +6,7 @@
 const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-react-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-react-router/src/play-router-provider.tsx#L38)
+Defined in: [play-react-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react-router/src/play-router-provider.tsx#L38)
 
 Connects a `PlayerActor` to React Router, keeping actor state and browser URL
 in sync bidirectionally.

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

@@ -331,10 +331,13 @@ npm test -w @xmachines/play-router
 npm run test:watch -w @xmachines/play-router
 ```
 
-The package exports a router bridge contract test suite for adapter authors:
+A router bridge contract test suite for adapter authors lives in
+`@xmachines/play-router-shared` (it drives a real actor, so it sits one layer
+above this package to keep `@xmachines/play-router` free of an actor-runtime
+dependency):
 
 ```typescript
-import { runBridgeContractTests } from "@xmachines/play-router/test/contract.js";
+import { runBridgeContractTests } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
 
 runBridgeContractTests({
 	name: "MyRouterBridge",
@@ -374,6 +377,7 @@ MIT — see [LICENSE](LICENSE).
 - [MachineNodeData](interfaces/MachineNodeData.md)
 - [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [ResolvedRoutePath](interfaces/ResolvedRoutePath.md)
 - [RoutableActor](interfaces/RoutableActor.md)
 - [RouteInfo](interfaces/RouteInfo.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L101)
 
 Shared bidirectional route map base class.
 
@@ -57,7 +57,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L127)
+Defined in: [base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L127)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -85,7 +85,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L218)
 
 Look up the path pattern registered for a state ID.
 
@@ -121,7 +121,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/base-route-map.ts#L178)
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L96)
+Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/router-bridge-base.ts#L96)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -30,7 +30,7 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L123)
+Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/router-bridge-base.ts#L123)
 
 #### Parameters
 
@@ -45,20 +45,6 @@ Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-
 
 `RouterBridgeBase`
 
-## Properties
-
-| Property                                                              | Modifier    | Type                                                                  | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                        |
-| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../interfaces/RoutableActor.md)                     | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L124) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L99)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L98)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                             | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [router-bridge-base.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L111) |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                    | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L100) |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                              | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. `getPathByStateId` may be keyed on either the `"#stateId"` or the bare `"stateId"` form — both forms are tried automatically by the bridge, so custom implementations (e.g. plain test objects) need only handle one.                                                                          | [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L125) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L127) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L126) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null` | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L112) |
-
 ## Methods
 
 ### connect()
@@ -67,7 +53,7 @@ Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L151)
+Defined in: [router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/router-bridge-base.ts#L151)
 
 Connect the router bridge to the Actor.
 
@@ -99,7 +85,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L256)
+Defined in: [router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/router-bridge-base.ts#L256)
 
 Disconnect the router bridge from the Actor.
 
@@ -112,338 +98,3 @@ Stops signal watching and unregisters framework-specific router listener.
 #### Implementation of
 
 [`RouterBridge`](../interfaces/RouterBridge.md).[`disconnect`](../interfaces/RouterBridge.md#disconnect)
-
----
-
-### extractParams()
-
-```ts
-protected extractParams(pathname, stateId): Record<string, string>;
-```
-
-Defined in: [router-bridge-base.ts:423](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L423)
-
-Extract path parameters from URL using the URLPattern API.
-
-Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-library. If `URLPattern` is unavailable and the matched route has parameterized
-segments, a `URLPatternUnavailableError` is thrown — callers must provide a polyfill
-for environments without native URLPattern support (Node.js < 24, older browsers).
-
-#### Parameters
-
-| Parameter  | Type     | Description                                           |
-| ---------- | -------- | ----------------------------------------------------- |
-| `pathname` | `string` | The actual URL path (e.g., '/profile/john')           |
-| `stateId`  | `string` | The matched state ID for looking up the route pattern |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted path parameters, or empty object if no match
-
-#### Throws
-
-When URLPattern is absent and the route is parameterized
-
----
-
-### extractQuery()
-
-```ts
-protected extractQuery(search): Record<string, string>;
-```
-
-Defined in: [router-bridge-base.ts:480](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L480)
-
-Extract query parameters from URL search string.
-
-#### Parameters
-
-| Parameter | Type     | Description                                      |
-| --------- | -------- | ------------------------------------------------ |
-| `search`  | `string` | URL search string (e.g., '?tab=security&page=1') |
-
-#### Returns
-
-`Record`\<`string`, `string`\>
-
-Extracted query parameters or empty object
-
----
-
-### getInitialRouterPath()
-
-```ts
-protected getInitialRouterPath(): string | null | undefined;
-```
-
-Defined in: [router-bridge-base.ts:559](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L559)
-
-Return the router's current pathname at connect() time.
-
-Called once during connect() to perform the initial URL → actor sync.
-router.subscribe() only fires on _future_ navigation events; it does not
-replay the already-loaded location. Subclasses that can read the router's
-current location synchronously (e.g. `router.state.location.pathname`)
-should override this method so that deep-link / direct-URL loads drive the
-actor to the correct state instead of leaving it at its machine default.
-
-Return semantics:
-
-- `string` → router has a current path; base connect() will sync actor from router
-- `null` → router is active but has no current path yet; base connect() will sync router from actor
-- `undefined` → adapter handles initial sync itself and base connect() should stay out of the way
-
-The default returns `undefined`, preserving the previous behaviour for
-bridges that have not yet implemented this hook.
-
-#### Returns
-
-`string` \| `null` \| `undefined`
-
----
-
-### getInitialRouterSearch()
-
-```ts
-protected getInitialRouterSearch(): string | undefined;
-```
-
-Defined in: [router-bridge-base.ts:576](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L576)
-
-Return the router's current search string at connect() time.
-
-Paired with `getInitialRouterPath()` — called once during connect() to pass
-the initial URL query string to `syncActorFromRouter()`. If the router's current
-URL has no search (or the subclass doesn't override this), returns `undefined`
-and `syncActorFromRouter` will produce an empty `query: {}` in the event.
-
-Subclasses that override `getInitialRouterPath()` and have a query string
-available should also override this method.
-
-#### Returns
-
-`string` \| `undefined`
-
-URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
-
----
-
-### navigateRouter()
-
-```ts
-abstract protected navigateRouter(path): void;
-```
-
-Defined in: [router-bridge-base.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L495)
-
-Must trigger the framework router's navigation (e.g., router.navigate(path)).
-
-Contract: `path` is always a RESOLVED concrete URL path (e.g. `"/home"`).
-The base class resolves actor route values (stateIds like `"#home"`,
-parameterized patterns) via `resolveNavigationPath()` before calling this
-method and skips the push entirely when resolution fails — implementations
-must NOT re-resolve and can push the value as-is.
-
-#### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `path`    | `string` |
-
-#### Returns
-
-`void`
-
----
-
-### resolveNavigationPath()
-
-```ts
-protected resolveNavigationPath(route): string | null;
-```
-
-Defined in: [router-bridge-base.ts:447](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L447)
-
-Resolve an actor route value to a concrete URL path for navigation.
-
-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 or wildcard pattern (e.g. `/profile/:id`, `/docs/*`) — no
-  concrete values available to build a real URL
-- non-path string that isn't a known stateId
-
-StateId lookups try both the `"#stateId"` and bare `"stateId"` forms
-automatically (via `lookupPathByStateId`), so custom route maps keyed on
-only one form still resolve.
-
-#### Parameters
-
-| Parameter | Type     | Description                                                    |
-| --------- | -------- | -------------------------------------------------------------- |
-| `route`   | `string` | Raw actor route value (stateId, `#`-stateId, or concrete path) |
-
-#### Returns
-
-`string` \| `null`
-
-Concrete URL path, or `null` if navigation should be skipped
-
----
-
-### sanitizePath()
-
-```ts
-protected sanitizePath(pathname): string | null;
-```
-
-Defined in: [router-bridge-base.ts:513](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L513)
-
-Sanitize and validate a raw URL pathname received from the router.
-
-Applies the path-length cap (2048 chars), strips query strings and fragments
-that may have been included in the pathname segment, and normalises
-consecutive slashes.
-
-Implementations that bypass `syncActorFromRouter()` (e.g. when using
-framework-native reactive watchers that receive pre-parsed route objects)
-MUST call this method before passing the path to any route-map lookup.
-`syncActorFromRouter()` calls this internally, so bridges that delegate
-to it do not need to call `sanitizePath` themselves.
-
-#### Parameters
-
-| Parameter  | Type     | Description                                 |
-| ---------- | -------- | ------------------------------------------- |
-| `pathname` | `string` | Raw URL pathname from the framework router. |
-
-#### Returns
-
-`string` \| `null`
-
-Sanitized pathname, or `null` if the path is invalid / too long.
-
----
-
-### syncActorFromRouter()
-
-```ts
-protected syncActorFromRouter(pathname, search?): void;
-```
-
-Defined in: [router-bridge-base.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L347)
-
-Sync actor state when router location changes.
-
-**Known path:** sends a `play.route` event to the actor with the matched
-stateId, params, and query. Prevents circular updates via the
-`isProcessingNavigation` flag.
-
-**Unknown/unmapped path:** does NOT send a `play.route` event (actor state
-is unchanged). Instead, actively corrects the browser URL by calling
-`navigateRouter(actor.currentRoute.get())` — keeping the URL in sync with
-actor state even when the user types an invalid path into the address bar
-or pushes one programmatically mid-session. `lastSyncedPath` is set to the
-resolved concrete path before calling `navigateRouter` so the router's own
-callback for that navigation short-circuits the echo-suppression guard and
-sends no spurious event.
-
-#### Parameters
-
-| Parameter  | Type     |
-| ---------- | -------- |
-| `pathname` | `string` |
-| `search?`  | `string` |
-
-#### Returns
-
-`void`
-
----
-
-### syncRouterFromActor()
-
-```ts
-protected syncRouterFromActor(route): void;
-```
-
-Defined in: [router-bridge-base.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L302)
-
-Sync router location when actor route signal changes.
-
-Resolves the actor route to a concrete URL path and calls navigateRouter()
-for framework-specific navigation. When the route cannot be resolved
-(unknown stateId, parameterized pattern with no concrete values) the push
-is skipped entirely — `navigateRouter` is never called with a raw stateId
-or pattern.
-
-Echo suppression — preventing the router's own callback from re-driving the
-actor — is handled entirely by `lastSyncedPath`: it is set to the resolved
-path before `navigateRouter()` is called, so any `syncActorFromRouter`
-invocation for the same path short-circuits at the
-`sanitized === lastSyncedPath` check and sends no event regardless of
-whether the callback fires synchronously or asynchronously.
-
-`isProcessingNavigation` is NOT set here — it is only used inside
-`syncActorFromRouter` to guard against re-entrant guard-redirect loops.
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `route`   | `unknown` |
-
-#### Returns
-
-`void`
-
----
-
-### unwatchRouterChanges()
-
-```ts
-abstract protected unwatchRouterChanges(): void;
-```
-
-Defined in: [router-bridge-base.ts:539](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L539)
-
-Stop watching for router location changes.
-
-Called by disconnect(). Should clean up the framework-specific subscription.
-
-#### Returns
-
-`void`
-
----
-
-### watchRouterChanges()
-
-```ts
-abstract protected watchRouterChanges(): void;
-```
-
-Defined in: [router-bridge-base.ts:532](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L532)
-
-Start watching for router location changes.
-
-Called by connect(). Should set up the framework-specific subscription
-for location changes and call syncActorFromRouter() on each change.
-
-**Implementations that call `syncActorFromRouter`** get path sanitization
-applied automatically — no extra work needed.
-
-**Implementations that bypass `syncActorFromRouter`** (e.g. `VueRouterBridge`,
-which builds the `play.route` event directly from framework-native route params)
-MUST call `this.sanitizePath(path)` and return early when it returns `null`.
-Skipping this allows oversized or malformed paths through without the length
-and content guards that protect the route-map lookup.
-
-#### Returns
-
-`void`

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

@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [router-sync.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-sync.ts#L168)
+Defined in: [router-sync.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/router-sync.ts#L168)
 
 Build a normalized `play.route` event from raw router/browser input.
 

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

@@ -6,7 +6,7 @@
 function buildRouteTree(routes): RouteTree;
 ```
 
-Defined in: [build-tree.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/build-tree.ts#L21)
+Defined in: [build-tree.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/build-tree.ts#L21)
 
 Build hierarchical route tree from flat route list
 

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

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

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

@@ -6,7 +6,7 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
 Create a `RouteMap` from a `RouteTree` node structure.