@xmachines/docs 1.0.0-beta.24 → 1.0.0-beta.26

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

@@ -0,0 +1,104 @@
+[Documentation](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L271)
+
+RouterBridge interface for runtime infrastructure adapters
+
+Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+the Actor. Infrastructure "bridges" to the Actor by observing its signals and
+managing its own lifecycle accordingly.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
+a unidirectional observation pattern. Infrastructure connects to observe Actor signals
+(currentRoute, currentView, state) and reflects changes without making state decisions.
+
+## Example
+
+TanStack Router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class TanStackRouterBridge implements RouterBridge {
+	private watcher: Signal.Watcher | null = null;
+
+	async connect(): Promise<void> {
+		// Start observing actor.currentRoute signal
+		this.watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			if (route) router.navigate(route);
+		});
+		this.watcher.watch(actor.currentRoute);
+	}
+
+	async disconnect(): Promise<void> {
+		// Stop observing, cleanup watchers
+		this.watcher?.unwatch(actor.currentRoute);
+		this.watcher = null;
+	}
+}
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L287)
+
+Connect the router bridge to the Actor
+
+Called when Infrastructure should begin observing Actor signals and
+synchronizing its state (e.g., browser URL) with Actor state.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when connection is established, or void for synchronous connection
+
+#### Example
+
+```typescript
+const bridge: RouterBridge = createBridge(actor, router);
+await bridge.connect();
+// Bridge now observing actor.currentRoute signal
+```
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void | Promise<void>;
+```
+
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L303)
+
+Disconnect the router bridge from the Actor
+
+Called when Infrastructure should stop observing and clean up resources
+(e.g., signal watchers, event listeners).
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when disconnection is complete, or void for synchronous disconnection
+
+#### Example
+
+```typescript
+await bridge.disconnect();
+// Bridge stopped observing, resources cleaned up
+```

package/api/@xmachines/play-sveltekit-router/type-aliases/RoutableActor.md

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RoutableActor
+
+# Type Alias: RoutableActor
+
+```ts
+type RoutableActor = AbstractActor<AnyActorLogic> & Routable;
+```
+
+Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-sveltekit-router/src/types.ts#L10)

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

@@ -0,0 +1,23 @@
+[Documentation](../../README.md) / @xmachines/play-sveltekit-router-demo
+
+# @xmachines/play-sveltekit-router demo
+
+Compact browser demo for the SvelteKit router adapter.
+
+## Imports
+
+- `@xmachines/play-svelte` for the Svelte renderer and registry helpers
+- `@xmachines/play-sveltekit-router` for URL ↔ actor sync
+
+## Commands
+
+```bash
+npm run dev -w @xmachines/play-sveltekit-router-demo
+npm run build -w @xmachines/play-sveltekit-router-demo
+npm run test:browser -w @xmachines/play-sveltekit-router-demo
+```
+
+## What it proves
+
+- Clicking a navigation control updates the rendered view
+- The browser pathname follows the active route

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

@@ -123,6 +123,10 @@ function createRouteMapFromTree(routeTree: RouteTree): RouteMap
 
 `getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
 
+`createRouteMapFromTree` uses `node.fullPath` (the fully resolved absolute path) for all
+route entries. This is correct for both flat routes (e.g. `"/login"`) and nested relative
+routes (e.g. `meta.route: "overview"` under `"/dashboard"` resolves to `"/dashboard/overview"`).
+
 ```ts
 const routeMap = new RouteMap([
 	{ stateId: "home", path: "/" },
@@ -166,7 +170,7 @@ interface PlayRouterProviderProps {
 
 Bridge-first flow:
 
-1. `RouterBridgeBase.connect()` performs initial actor/router synchronization.
+1. `RouterBridgeBase.connect()` performs initial actor/router synchronization — both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
 2. Actor route updates call TanStack navigation (`router.navigate({ to })`).
 3. TanStack history updates are subscribed and translated to `play.route` events.
 4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
@@ -214,6 +218,4 @@ Synchronizes browser URL with actor state through passive infrastructure.
 - [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
 - [extractMachineRoutes](functions/extractMachineRoutes.md)
-- [extractParams](functions/extractParams.md)
-- [extractQueryParams](functions/extractQueryParams.md)
 - [PlayRouterProvider](functions/PlayRouterProvider.md)

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

@@ -2,45 +2,25 @@
 
 # Class: RouteMap
 
-Defined in: [play-tanstack-react-router/src/route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/route-map.ts#L54)
+Defined in: [play-tanstack-react-router/src/route-map.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/route-map.ts#L12)
 
 Bidirectional route mapper for TanStack React Router.
 
-Extends [BaseRouteMap](../../play-router/classes/BaseRouteMap.md) — all matching logic lives there.
-This class exists to provide a TanStack React Router-specific type name and to
-allow future adapter-specific extensions without breaking the shared base.
-
-**Inherited API:**
-
-- `getStateIdByPath(path): string | null` — path → state ID
-- `getPathByStateId(stateId): string | null` — state ID → path pattern
-
-## Example
-
-```typescript
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
-
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-```
+Alias for [BaseRouteMap](../../play-dom-router/interfaces/RouteMap.md) from `@xmachines/play-router`.
 
 ## Extends
 
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+- [`RouteMap`](../../play-dom-router/interfaces/RouteMap.md)
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new RouteMap(mappings): RouteMap;
+new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/base-route-map.ts#L118)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -50,9 +30,11 @@ buckets for efficient candidate selection.
 
 #### Parameters
 
-| Parameter  | Type                                                                     | Description                                                                                                       |
-| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
@@ -60,7 +42,9 @@ buckets for efficient candidate selection.
 
 #### Inherited from
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+```ts
+BaseRouteMap.constructor;
+```
 
 ## Methods
 
@@ -70,7 +54,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/base-route-map.ts#L202)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -95,7 +79,7 @@ map.getPathByStateId("missing"); // null
 
 #### Inherited from
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
+[`RouteMap`](../../play-dom-router/interfaces/RouteMap.md).[`getPathByStateId`](../../play-dom-router/interfaces/RouteMap.md#getpathbystateid)
 
 ---
 
@@ -105,7 +89,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/base-route-map.ts#L167)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 
@@ -134,4 +118,4 @@ map.getStateIdByPath("/unknown"); // null
 
 #### Inherited from
 
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)
+[`RouteMap`](../../play-dom-router/interfaces/RouteMap.md).[`getStateIdByPath`](../../play-dom-router/interfaces/RouteMap.md#getstateidbypath)

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

@@ -2,7 +2,7 @@
 
 # Class: TanStackReactRouterBridge
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L80)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L83)
 
 TanStack React Router adapter implementing RouterBridge protocol via RouterBridgeBase
 
@@ -47,7 +47,7 @@ new TanStackReactRouterBridge(
    routeMap): TanStackReactRouterBridge;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L90)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L93)
 
 Create TanStack React Router bridge
 
@@ -71,15 +71,15 @@ Create TanStack React Router bridge
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L102) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L90)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L89)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L92)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L91)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L103) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L105) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L93)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L89)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L102) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L101) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L90)   |
 
 ## Methods
 
@@ -89,7 +89,7 @@ Create TanStack React Router bridge
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L129)
+Defined in: [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L126)
 
 Connect the router bridge to the Actor.
 
@@ -121,7 +121,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L197)
+Defined in: [play-router/src/router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L209)
 
 Disconnect the router bridge from the Actor.
 
@@ -143,14 +143,14 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:300](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L300)
+Defined in: [play-router/src/router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L318)
 
 Extract path parameters from URL using the URLPattern API.
 
 Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-library. If `URLPattern` is unavailable (Node.js < 24, older browsers without a
-polyfill), this method returns `{}` silently (graceful degradation — routing still
-works, params will be empty).
+library. If `URLPattern` is unavailable and the matched route has parameterized
+segments, a `URLPatternUnavailableError` is thrown — callers must provide a polyfill
+for environments without native URLPattern support (Node.js < 24, older browsers).
 
 #### Parameters
 
@@ -163,7 +163,11 @@ works, params will be empty).
 
 `Record`\<`string`, `string`\>
 
-Extracted path parameters, or empty object if URLPattern is unavailable or no match
+Extracted path parameters, or empty object if no match
+
+#### Throws
+
+When URLPattern is absent and the route is parameterized
 
 #### Inherited from
 
@@ -177,7 +181,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:321](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L321)
+Defined in: [play-router/src/router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L355)
 
 Extract query parameters from URL search string.
 
@@ -205,7 +209,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L123)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L126)
 
 Read the router's current pathname for initial sync.
 
@@ -234,13 +238,38 @@ The base class `connect()` uses `actor.initialRoute` to distinguish:
 
 ---
 
+### getInitialRouterSearch()
+
+```ts
+protected getInitialRouterSearch(): string | undefined;
+```
+
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L142)
+
+Return the initial URL search string for query-param forwarding on `connect()`.
+
+Reads `router.history.location.search` — the same source used by
+`getInitialRouterPath()`, which reflects `window.location` immediately before
+`router.load()` or `<RouterProvider>` mounts. An empty string returns `undefined`
+so `syncActorFromRouter` produces `query: {}` rather than parsing an empty string.
+
+#### Returns
+
+`string` \| `undefined`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`getInitialRouterSearch`](../../play-router/classes/RouterBridgeBase.md#getinitialroutersearch)
+
+---
+
 ### navigateRouter()
 
 ```ts
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L102)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L105)
 
 Navigate the framework router to the given path.
 
@@ -263,13 +292,52 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 
 ---
 
+### resolveNavigationPath()
+
+```ts
+protected resolveNavigationPath(route): string | null;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L340)
+
+Resolve an actor route value to a concrete URL path for navigation.
+
+Bridges that receive raw `actor.currentRoute` values in `navigateRouter`
+can call this to normalize stateIds (with or without `#` prefix) to paths.
+Returns `null` when navigation is not possible:
+
+- unknown stateId with no route map entry
+- parameterized pattern (e.g. `/profile/:id`) — no concrete values available
+- non-path string that isn't a known stateId
+
+Route maps may store stateIds with or without the `#` prefix; both forms
+are tried automatically.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                    |
+| --------- | -------- | -------------------------------------------------------------- |
+| `route`   | `string` | Raw actor route value (stateId, `#`-stateId, or concrete path) |
+
+#### Returns
+
+`string` \| `null`
+
+Concrete URL path, or `null` if navigation should be skipped
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`resolveNavigationPath`](../../play-router/classes/RouterBridgeBase.md#resolvenavigationpath)
+
+---
+
 ### syncActorFromRouter()
 
 ```ts
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [play-router/src/router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L260)
 
 Sync actor state when router location changes.
 
@@ -299,7 +367,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/router-bridge-base.ts#L228)
+Defined in: [play-router/src/router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-bridge-base.ts#L240)
 
 Sync router location when actor route signal changes.
 
@@ -332,7 +400,7 @@ suppressed as circular echoes.
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L148)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L163)
 
 Stop watching for router location changes.
 
@@ -354,7 +422,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L140)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L155)
 
 Subscribe to ALL navigation events via router.history.
 

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

@@ -6,7 +6,7 @@
 function PlayRouterProvider<TActor>(__namedParameters): Element;
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-tanstack-react-router/src/play-router-provider.tsx#L41)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-tanstack-react-router/src/play-router-provider.tsx#L41)
 
 ## Type Parameters
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(routeTree): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.24/packages/play-router/src/create-route-map.ts#L74)
+Defined in: [play-router/src/create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/create-route-map.ts#L74)
 
 Create a RouteMap from a RouteTree for efficient path lookups.
 

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

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

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

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