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

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

@@ -2,14 +2,15 @@
 
 # Class: TanStackReactRouterBridge
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L83)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
 
-TanStack React Router adapter implementing RouterBridge protocol via RouterBridgeBase
+Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
 
 ## Remarks
 
-Extends RouterBridgeBase to handle all common lifecycle and sync logic.
-Only 3 TanStack-specific methods are implemented here.
+Extends RouterBridgeBase to handle all common lifecycle and sync logic; adds
+the TanStack-specific navigation and subscription methods shared by the React
+and Solid adapters.
 
 Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
 back/forward browser navigation (popstate events) are also captured. The
@@ -24,10 +25,14 @@ Architectural Invariants:
 - INV-02 (Passive Infrastructure): Router reflects actor state, never decides
 - Actor validates all navigation via guards before URL changes
 
+The class is concrete — it can be instantiated directly. The framework
+packages re-export or subclass it purely to bind the public adapter name
+(and, for Solid, to add the `dispose()` alias).
+
 ## Example
 
 ```typescript
-const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
+const bridge = new TanStackRouterBridgeBase(router, actor, routeMap);
 bridge.connect();
 return () => bridge.disconnect();
 ```
@@ -44,24 +49,24 @@ return () => bridge.disconnect();
 new TanStackReactRouterBridge(
    router,
    actor,
-   routeMap): TanStackReactRouterBridge;
+   routeMap): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L93)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
 
-Create TanStack React Router bridge
+Create a TanStack Router bridge
 
 #### Parameters
 
-| Parameter  | Type                                                                 | Description                                       |
-| ---------- | -------------------------------------------------------------------- | ------------------------------------------------- |
-| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)        | TanStack React Router instance                    |
-| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | XMachines actor instance                          |
-| `routeMap` | [`RouteMap`](RouteMap.md)                                            | Bidirectional mapping between state IDs and paths |
+| Parameter  | Type                                                                                      | Description                                       |
+| ---------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                             | TanStack Router instance (from `createRouter`)    |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                      | XMachines actor instance                          |
+| `routeMap` | [`TanStackRouteMapLike`](../../play-tanstack-router/type-aliases/TanStackRouteMapLike.md) | Bidirectional mapping between state IDs and paths |
 
 #### Returns
 
-`TanStackReactRouterBridge`
+`TanStackRouterBridgeBase`
 
 #### Overrides
 
@@ -69,17 +74,18 @@ Create TanStack React Router bridge
 
 ## Properties
 
-| Property                                                              | Modifier    | Type                                                                                    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
-| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                    | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L125) |
-| <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:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L103) |
-| <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:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L102) |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                               | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L115) |
-| <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:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent.                                                                                                                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L126) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L128) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L127) |
-| <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:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L116) |
+| Property                                                              | Modifier    | Type                                                                                    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                                                            |
+| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                    | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L124)                                     |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                               | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L99)                                       |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                               | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L98)                                       |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                               | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L111)                                     |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                      | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L100)                                     |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. `getPathByStateId` may be keyed on either the `"#stateId"` or the bare `"stateId"` form — both forms are tried automatically by the bridge, so custom implementations (e.g. plain test objects) need only handle one.                                                                          | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L125)                                     |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L127)                                     |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L126)                                     |
+| <a id="property-router"></a> `router`                                 | `readonly`  | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                           | `undefined`   | TanStack Router instance (from `createRouter`)                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                                                             | [play-tanstack-router/src/tanstack-router-bridge-base.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L113) |
+| <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:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L112)                                     |
 
 ## Methods
 
@@ -89,7 +95,7 @@ Create TanStack React Router bridge
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L152)
+Defined in: [play-router/src/router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L151)
 
 Connect the router bridge to the Actor.
 
@@ -121,7 +127,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [play-router/src/router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L256)
 
 Disconnect the router bridge from the Actor.
 
@@ -143,7 +149,7 @@ 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:402](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L402)
+Defined in: [play-router/src/router-bridge-base.ts:423](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L423)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -181,7 +187,7 @@ When URLPattern is absent and the route is parameterized
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L439)
+Defined in: [play-router/src/router-bridge-base.ts:480](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L480)
 
 Extract query parameters from URL search string.
 
@@ -209,7 +215,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L127)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:153](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L153)
 
 Read the router's current pathname for initial sync.
 
@@ -220,7 +226,7 @@ while logged out — the actor must be redirected to /login before rendering).
 Uses `router.history.location.pathname` — reflects `window.location` immediately,
 before the router has been loaded or a `<RouterProvider>` mounted.
 `router.state.location` is only populated after `router.load()` which may not
-have run yet when the bridge first connects in a `useEffect`.
+have run yet when the bridge first connects in a component effect.
 
 The base class `connect()` uses `actor.initialRoute` to distinguish:
 
@@ -244,7 +250,7 @@ The base class `connect()` uses `actor.initialRoute` to distinguish:
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:143](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L143)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L169)
 
 Return the initial URL search string for query-param forwarding on `connect()`.
 
@@ -269,9 +275,13 @@ so `syncActorFromRouter` produces `query: {}` rather than parsing an empty strin
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L105)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L131)
+
+Navigate TanStack Router to the given path.
 
-Must trigger the framework router's navigation (e.g., router.navigate(path)).
+Calls `router.load()` (fire-and-forget) after `navigate` so TanStack re-runs
+route matching and loaders — `navigate` alone does not when no
+`<RouterProvider>` (Transitioner) is mounted.
 
 #### Parameters
 
@@ -295,7 +305,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:424](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L424)
+Defined in: [play-router/src/router-bridge-base.ts:447](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L447)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -304,11 +314,13 @@ 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
+- parameterized or wildcard pattern (e.g. `/profile/:id`, `/docs/*`) — no
+  concrete values available to build a real URL
 - non-path string that isn't a known stateId
 
-Route maps may store stateIds with or without the `#` prefix; both forms
-are tried automatically.
+StateId lookups try both the `"#stateId"` and bare `"stateId"` forms
+automatically (via `lookupPathByStateId`), so custom route maps keyed on
+only one form still resolve.
 
 #### Parameters
 
@@ -334,7 +346,7 @@ Concrete URL path, or `null` if navigation should be skipped
 protected sanitizePath(pathname): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:466](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L466)
+Defined in: [play-router/src/router-bridge-base.ts:513](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L513)
 
 Sanitize and validate a raw URL pathname received from the router.
 
@@ -372,7 +384,7 @@ Sanitized pathname, or `null` if the path is invalid / too long.
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L324)
+Defined in: [play-router/src/router-bridge-base.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L347)
 
 Sync actor state when router location changes.
 
@@ -412,17 +424,22 @@ sends no spurious event.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:289](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L289)
+Defined in: [play-router/src/router-bridge-base.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/router-bridge-base.ts#L302)
 
 Sync router location when actor route signal changes.
 
-Calls navigateRouter() for framework-specific navigation.
+Resolves the actor route to a concrete URL path and calls navigateRouter()
+for framework-specific navigation. When the route cannot be resolved
+(unknown stateId, parameterized pattern with no concrete values) the push
+is skipped entirely — `navigateRouter` is never called with a raw stateId
+or pattern.
 
 Echo suppression — preventing the router's own callback from re-driving the
-actor — is handled entirely by `lastSyncedPath`: it is set to `route` before
-`navigateRouter()` is called, so any `syncActorFromRouter` invocation for the
-same path short-circuits at the `sanitized === lastSyncedPath` check and sends
-no event regardless of whether the callback fires synchronously or asynchronously.
+actor — is handled entirely by `lastSyncedPath`: it is set to the resolved
+path before `navigateRouter()` is called, so any `syncActorFromRouter`
+invocation for the same path short-circuits at the
+`sanitized === lastSyncedPath` check and sends no event regardless of
+whether the callback fires synchronously or asynchronously.
 
 `isProcessingNavigation` is NOT set here — it is only used inside
 `syncActorFromRouter` to guard against re-entrant guard-redirect loops.
@@ -449,11 +466,9 @@ no event regardless of whether the callback fires synchronously or asynchronousl
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L165)
-
-Stop watching for router location changes.
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:196](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L196)
 
-Called by disconnect(). Should clean up the framework-specific subscription.
+Stop watching TanStack Router changes.
 
 #### Returns
 
@@ -471,7 +486,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:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L156)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L184)
 
 Subscribe to ALL navigation events via router.history.
 
@@ -479,7 +494,9 @@ router.history.subscribe fires for PUSH, POP, BACK, FORWARD, REPLACE, and GO —
 covering both link clicks and browser back/forward button presses.
 
 The subscriber callback receives { location, action } where location is the
-new history location with pathname and search already updated.
+new history location with pathname and search already updated. It calls
+`router.load()` (fire-and-forget) so TanStack re-runs matching/loaders for the
+new location, mirroring what Transitioner does when `<RouterProvider>` is mounted.
 
 #### Returns
 

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

@@ -0,0 +1,45 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / createPlayRouterProvider
+
+# Function: createPlayRouterProvider()
+
+```ts
+function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(__namedParameters) => Element;
+```
+
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L92)
+
+Create a React `PlayRouterProvider` component bound to a specific bridge class.
+
+The returned component connects a `PlayerActor` to the framework router,
+keeping actor state and browser URL in sync bidirectionally.
+
+The bridge is created once on mount and torn down on unmount. It is also
+rebuilt if `actor`, `router`, or `routeMap` change identity — so all three
+props must be **stable references** (created outside JSX or memoized).
+Under React `<StrictMode>` the effect runs twice on mount
+(connect → disconnect → connect), which the bridges support.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TRouter`      |
+
+## Parameters
+
+| Parameter    | Type                                                                                         | Description                                                            |
+| ------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | Bridge class constructed as `new BridgeCtor(router, actor, routeMap)`. |
+
+## Returns
+
+A `PlayRouterProvider` component, generic over the actor type so the
+`renderer` callback receives the same concrete actor type that was passed in.
+
+\<`TActor`\>(`__namedParameters`) => `Element`
+
+## Example
+
+```tsx
+export const PlayRouterProvider = createPlayRouterProvider(TanStackReactRouterBridge);
+```

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

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

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

@@ -6,11 +6,11 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
 Create a `RouteMap` from a `RouteTree` node structure.
 
-Used by framework-router adapters (React Router, TanStack Router) that pass a
+Used by framework-router adapters that pass a
 `RouteTree` produced by `extractMachineRoutes()` rather than calling
 `createRouteMap()` directly.
 

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.52/packages/play-router/src/extract-routes.ts#L93)
+Defined in: [play-router/src/extract-routes.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/extract-routes.ts#L89)
 
 Extract complete route tree from state machine graph
 

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

@@ -2,11 +2,11 @@
 
 # Interface: PlayActor
 
-Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L297)
+Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L297)
 
 Full actor shape used by `PlayRouterProvider` components across all framework
-adapters (`play-solid-router`, `play-tanstack-solid-router`, `play-vue-router`,
-`play-tanstack-react-router`, `play-react-router`).
+adapters (`play-solid-router`, `play-vue-router`, `play-react-router`, and the
+adapters built on the shared framework-router bridge bases).
 
 Extends `RoutableActor` with `currentView` — the provider renders the current
 view spec in addition to synchronizing routes, so it needs both capabilities.
@@ -37,9 +37,9 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 
 | Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                                                                                                 | Defined in                                                                                                                              |
 | ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L261) |
-| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L299) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L267) |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L261) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L299) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L267) |
 
 ## Methods
 
@@ -49,7 +49,7 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L269)
+Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L269)
 
 Send a route navigation event to the actor.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L225)
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L225)
 
 Enhanced routing event with parameter and query support
 
@@ -22,22 +22,32 @@ via `play.route` events, Actor decides via state machine transitions.
 
 ## Param
 
+**type**
+
 Event discriminator (always "play.route")
 
 ## Param
 
+**to**
+
 Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
+**params**
+
 Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
+**query**
+
 Query parameters only (isolated from path params)
 
 ## Param
 
+**match**
+
 Full URLPattern match result for debugging/observability (optional)
 
 ## Examples
@@ -112,8 +122,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L230) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L228) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L229) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L227) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/types.ts#L226) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-router/src/types.ts#L226) |

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

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-react-router](../README.md) / PlayRouterProviderBaseProps
+
+# Interface: PlayRouterProviderBaseProps\<TRouter, TActor\>
+
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L45)
+
+Props shared by every factory-created React `PlayRouterProvider`.
+
+Adapter packages re-export a concrete alias with `TRouter` bound to their
+router instance type (e.g. `PlayRouterProviderProps<TActor>` in
+`@xmachines/play-tanstack-react-router` binds `TRouter` to the TanStack Router
+instance type).
+
+## Extended by
+
+- [`PlayRouterProviderProps`](PlayRouterProviderProps.md)
+
+## Type Parameters
+
+| Type Parameter                                 | Default type                |
+| ---------------------------------------------- | --------------------------- |
+| `TRouter`                                      | -                           |
+| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
+
+## Properties
+
+| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                                                                                        |
+| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with the router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                                    | [play-tanstack-react-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L51) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                                              | [play-tanstack-react-router/src/create-play-router-provider.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L68) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMapFromTree(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [play-tanstack-react-router/src/create-play-router-provider.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L66) |
+| <a id="property-router"></a> `router`     | `TRouter`                            | The router instance the bridge synchronizes with. Must be a stable reference.                                                                                                                                                                                                                                                                                                                                            | [play-tanstack-react-router/src/create-play-router-provider.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.54/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L53) |