@xmachines/docs 1.0.0-beta.15 → 1.0.0-beta.17

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L56)
+Defined in: [router-bridge-base.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L82)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -30,18 +30,16 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L70)
-
-Constructor receives the 3 things all bridges need.
+Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L96)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                                                                                          | Description                                           |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `actor`                     | [`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        |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                                                                           | Bidirectional route map for stateId ↔ path resolution |
-| `routeMap.getPathByStateId` | -                                                                                                                                                                                             |
-| `routeMap.getStateIdByPath` | -                                                                                                                                                                                             |
+| Parameter                   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                      |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `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) | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           |
+| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                                                                                                                                              | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. |
+| `routeMap.getPathByStateId` | -                                                                                                                                                                                                                                                                |
+| `routeMap.getStateIdByPath` | -                                                                                                                                                                                                                                                                |
 
 #### Returns
 
@@ -49,17 +47,17 @@ Constructor receives the 3 things all bridges need.
 
 ## Properties
 
-| Property                                                              | Modifier    | Type                                                                                                                                                                                          | Default value | Description                                           | 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) | `undefined`   | Actor with currentRoute signal and send method        | [router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L71) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                     | `false`       | -                                                     | [router-bridge-base.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L59) |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                     | `false`       | -                                                     | [router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L58) |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                     | `false`       | -                                                     | [router-bridge-base.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L61) |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string`                                                                                                                                                                                      | `""`          | -                                                     | [router-bridge-base.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L60) |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                      | `undefined`   | Bidirectional route map for stateId ↔ path resolution | [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L72) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                             | `undefined`   | -                                                     | [router-bridge-base.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L74) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                             | `undefined`   | -                                                     | [router-bridge-base.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L73) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`Watcher`](../../play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md) \| `null`                                                                                           | `null`        | -                                                     | [router-bridge-base.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L62) |
+| Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | 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`.                                                                                                                                           | [router-bridge-base.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L97)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L85)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L84)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <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. | [router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L98)   |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L88)   |
 
 ## Methods
 
@@ -69,7 +67,7 @@ Constructor receives the 3 things all bridges need.
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L90)
+Defined in: [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L116)
 
 Connect the router bridge to the Actor.
 
@@ -92,7 +90,7 @@ starts watching router changes (framework-specific).
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L140)
+Defined in: [router-bridge-base.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L184)
 
 Disconnect the router bridge from the Actor.
 
@@ -114,7 +112,7 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L276)
+Defined in: [router-bridge-base.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L283)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -125,10 +123,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 +142,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L303)
+Defined in: [router-bridge-base.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L310)
 
 Extract query parameters from URL search string.
 
@@ -165,12 +163,12 @@ Extracted query parameters or empty object
 ### getInitialRouterPath()
 
 ```ts
-protected getInitialRouterPath(): string | null;
+protected getInitialRouterPath(): string | null | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:353](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L353)
+Defined in: [router-bridge-base.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L357)
 
-Return the router's current pathname at connect() time, or null if unavailable.
+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
@@ -179,12 +177,18 @@ 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.
 
-The default returns null (no initial router → actor sync), preserving the
-previous behaviour for bridges that have not yet implemented this hook.
+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`
+`string` \| `null` \| `undefined`
 
 ---
 
@@ -194,7 +198,7 @@ previous behaviour for bridges that have not yet implemented this hook.
 abstract protected navigateRouter(path): void;
 ```
 
-Defined in: [router-bridge-base.ts:323](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L323)
+Defined in: [router-bridge-base.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L322)
 
 Navigate the framework router to the given path.
 
@@ -219,7 +223,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [router-bridge-base.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L187)
+Defined in: [router-bridge-base.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L231)
 
 Sync actor state when router location changes.
 
@@ -245,7 +249,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [router-bridge-base.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L167)
+Defined in: [router-bridge-base.ts:211](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L211)
 
 Sync router location when actor route signal changes.
 
@@ -270,7 +274,7 @@ Prevents circular updates via isProcessingNavigation flag.
 abstract protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L338)
+Defined in: [router-bridge-base.ts:337](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L337)
 
 Stop watching for router location changes.
 
@@ -288,7 +292,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 abstract protected watchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:331](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/router-bridge-base.ts#L331)
+Defined in: [router-bridge-base.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/router-bridge-base.ts#L330)
 
 Start watching for router location changes.
 

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

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

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

@@ -6,7 +6,7 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [connect-router.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/connect-router.ts#L58)
+Defined in: [connect-router.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/connect-router.ts#L59)
 
 Connect vanilla router to actor (pure browser integration).
 

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

@@ -6,7 +6,7 @@
 function crawlMachine(machine): StateVisit[];
 ```
 
-Defined in: [crawl-machine.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/crawl-machine.ts#L74)
+Defined in: [crawl-machine.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/crawl-machine.ts#L74)
 
 Crawl state machine graph using breadth-first traversal
 

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

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [create-browser-history.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L99)
+Defined in: [create-browser-history.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L115)
 
 Create browser history that wraps window.history
 
@@ -35,6 +35,9 @@ unsubscribe();
 history.destroy();
 ```
 
+`destroy()` is idempotent and cooperates with other wrappers created for the
+same `window` instance.
+
 ## Parameters
 
 | Parameter        | Type                                                               |

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

@@ -6,7 +6,7 @@
 function createRouteMap(routeTree): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-route-map.ts#L120)
+Defined in: [create-route-map.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-route-map.ts#L121)
 
 Create a RouteMap from a RouteTree for efficient path lookups.
 
@@ -27,8 +27,8 @@ before calling this function:
 import "urlpattern-polyfill"; // before importing @xmachines/play-router
 ```
 
-If `URLPattern` is unavailable, parameterized routes will not match and a
-`console.warn` is emitted. Static (exact) routes are unaffected.
+If `URLPattern` is unavailable, a `URLPatternUnavailableError` is thrown.
+Static (exact) routes are unaffected by URLPattern availability.
 
 Usage:
 

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

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [create-router.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-router.ts#L73)
+Defined in: [create-router.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-router.ts#L73)
 
 Create vanilla router for framework-agnostic routing.
 

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

@@ -6,7 +6,7 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/validate-routes.ts#L51)
+Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/validate-routes.ts#L51)
 
 Detect duplicate route paths
 

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

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

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

@@ -6,7 +6,7 @@
 function extractRoute(node, path, stateMap): RouteInfo | null;
 ```
 
-Defined in: [extract-route.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/extract-route.ts#L26)
+Defined in: [extract-route.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/extract-route.ts#L26)
 
 Extract route information from state node with validation
 

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

@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [index.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/index.ts#L69)
+Defined in: [index.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/index.ts#L70)
 
 Find route node by state ID
 

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

@@ -6,7 +6,7 @@
 function findRouteByPath(tree, path): RouteNode | undefined;
 ```
 
-Defined in: [index.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/index.ts#L161)
+Defined in: [index.ts:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/index.ts#L162)
 
 Find route node by URL path
 

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

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

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

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

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

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

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

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

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

@@ -6,7 +6,7 @@
 function validateStateExists(stateId, stateMap): void;
 ```
 
-Defined in: [validate-routes.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/validate-routes.ts#L32)
+Defined in: [validate-routes.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/validate-routes.ts#L32)
 
 Validate state exists in state map
 

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

@@ -2,7 +2,7 @@
 
 # Interface: BaseRouteMapping
 
-Defined in: [base-route-map.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/base-route-map.ts#L28)
+Defined in: [base-route-map.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L64)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/setting
 
 | Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                              |
 | --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/base-route-map.ts#L32) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/base-route-map.ts#L30) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L68) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/base-route-map.ts#L66) |

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

@@ -2,17 +2,17 @@
 
 # Interface: BrowserHistory
 
-Defined in: [create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L1)
+Defined in: [create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L1)
 
 ## Properties
 
 | Property                                  | Modifier   | Type      | Description                | Defined in                                                                                                                                            |
 | ----------------------------------------- | ---------- | --------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-location"></a> `location` | `readonly` | `object`  | Get current location state | [create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L5) |
-| `location.hash`                           | `public`   | `string`  | -                          | [create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L8) |
-| `location.pathname`                       | `public`   | `string`  | -                          | [create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L6) |
-| `location.search`                         | `public`   | `string`  | -                          | [create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L7) |
-| `location.state`                          | `public`   | `unknown` | -                          | [create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L9) |
+| <a id="property-location"></a> `location` | `readonly` | `object`  | Get current location state | [create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L5) |
+| `location.hash`                           | `public`   | `string`  | -                          | [create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L8) |
+| `location.pathname`                       | `public`   | `string`  | -                          | [create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L6) |
+| `location.search`                         | `public`   | `string`  | -                          | [create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L7) |
+| `location.state`                          | `public`   | `unknown` | -                          | [create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L9) |
 
 ## Methods
 
@@ -22,7 +22,7 @@ Defined in: [create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachine
 back(): void;
 ```
 
-Defined in: [create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L26)
+Defined in: [create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L26)
 
 #### Returns
 
@@ -36,7 +36,7 @@ Defined in: [create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachin
 createHref(path): string;
 ```
 
-Defined in: [create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L38)
+Defined in: [create-browser-history.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L38)
 
 Create href from path
 
@@ -58,9 +58,13 @@ Create href from path
 destroy(): void;
 ```
 
-Defined in: [create-browser-history.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L43)
+Defined in: [create-browser-history.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L47)
 
-Cleanup
+Cleanup.
+
+Safe to call more than once. When multiple wrappers share the same
+`window.history`, the original methods are restored only after the last
+wrapper is destroyed.
 
 #### Returns
 
@@ -74,7 +78,7 @@ Cleanup
 forward(): void;
 ```
 
-Defined in: [create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L27)
+Defined in: [create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L27)
 
 #### Returns
 
@@ -88,7 +92,7 @@ Defined in: [create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachin
 go(delta): void;
 ```
 
-Defined in: [create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L25)
+Defined in: [create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L25)
 
 Go back/forward
 
@@ -110,7 +114,7 @@ Go back/forward
 push(path, state?): void;
 ```
 
-Defined in: [create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L15)
+Defined in: [create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L15)
 
 Push new URL to history
 
@@ -133,7 +137,7 @@ Push new URL to history
 replace(path, state?): void;
 ```
 
-Defined in: [create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L20)
+Defined in: [create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L20)
 
 Replace current URL in history
 
@@ -156,7 +160,7 @@ Replace current URL in history
 subscribe(listener): () => void;
 ```
 
-Defined in: [create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L33)
+Defined in: [create-browser-history.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L33)
 
 Subscribe to history changes
 Returns unsubscribe function

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

@@ -2,7 +2,7 @@
 
 # Interface: BrowserWindow
 
-Defined in: [create-browser-history.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L55)
+Defined in: [create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L59)
 
 Minimal window interface for createBrowserHistory
 
@@ -14,17 +14,17 @@ Avoids coupling to `Window & typeof globalThis` which varies across environments
 
 | Property                                  | Modifier   | Type      | Defined in                                                                                                                                              |
 | ----------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`   | `public`   | `object`  | [create-browser-history.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L56) |
-| `history.state`                           | `readonly` | `unknown` | [create-browser-history.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L57) |
-| `history.back`                            | `public`   | `void`    | [create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L61) |
-| `history.forward`                         | `public`   | `void`    | [create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L62) |
-| `history.go`                              | `public`   | `void`    | [create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L60) |
-| `history.pushState`                       | `public`   | `void`    | [create-browser-history.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L58) |
-| `history.replaceState`                    | `public`   | `void`    | [create-browser-history.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L59) |
-| <a id="property-location"></a> `location` | `public`   | `object`  | [create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L64) |
-| `location.hash`                           | `readonly` | `string`  | [create-browser-history.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L67) |
-| `location.pathname`                       | `readonly` | `string`  | [create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L65) |
-| `location.search`                         | `readonly` | `string`  | [create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L66) |
+| <a id="property-history"></a> `history`   | `public`   | `object`  | [create-browser-history.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L60) |
+| `history.state`                           | `readonly` | `unknown` | [create-browser-history.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L61) |
+| `history.back`                            | `public`   | `void`    | [create-browser-history.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L65) |
+| `history.forward`                         | `public`   | `void`    | [create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L66) |
+| `history.go`                              | `public`   | `void`    | [create-browser-history.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L64) |
+| `history.pushState`                       | `public`   | `void`    | [create-browser-history.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L62) |
+| `history.replaceState`                    | `public`   | `void`    | [create-browser-history.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L63) |
+| <a id="property-location"></a> `location` | `public`   | `object`  | [create-browser-history.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L68) |
+| `location.hash`                           | `readonly` | `string`  | [create-browser-history.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L71) |
+| `location.pathname`                       | `readonly` | `string`  | [create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L69) |
+| `location.search`                         | `readonly` | `string`  | [create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L70) |
 
 ## Methods
 
@@ -34,7 +34,7 @@ Avoids coupling to `Window & typeof globalThis` which varies across environments
 addEventListener(type, listener): void;
 ```
 
-Defined in: [create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L69)
+Defined in: [create-browser-history.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L73)
 
 #### Parameters
 
@@ -55,7 +55,7 @@ Defined in: [create-browser-history.ts:69](https://gitlab.com/xmachin-es/xmachin
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [create-browser-history.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.15/packages/play-router/src/create-browser-history.ts#L70)
+Defined in: [create-browser-history.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-router/src/create-browser-history.ts#L74)
 
 #### Parameters