@xmachines/docs 2.1.0 → 2.2.0

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

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L39)
 
 The type-only interface of the TanStack Router surface that
 `TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
@@ -20,7 +20,7 @@ instance of `@tanstack/solid-router` both satisfy it.
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L46)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L72)
 
 #### location
 
@@ -61,6 +61,40 @@ subscribe(handler): () => void;
 
 () => `void`
 
+---
+
+### options?
+
+```ts
+optional options?: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L58)
+
+The options of the router. The bridge reads `parseSearch` only.
+
+TanStack owns the encoding of a query: its default `stringifySearch` writes each
+value through `JSON.stringify`, so a plain string arrives in the URL with quotes
+around it. `parseSearch` is the inverse, and it is therefore the only correct way
+to turn a query string of the URL into the `search` object that `navigate`
+accepts. A router double may hold neither.
+
+#### parseSearch()?
+
+```ts
+optional parseSearch(search): Record<string, unknown>;
+```
+
+##### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `search`  | `string` |
+
+##### Returns
+
+`Record`\<`string`, `unknown`\>
+
 ## Methods
 
 ### load()?
@@ -69,12 +103,18 @@ subscribe(handler): () => void;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L45)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 Runs the TanStack route matching and the loaders again for the current location.
-This method is optional. The bridge calls it after every navigation, and it does
-not wait for the result. The matching and the loaders therefore stay correct,
-also when no `<RouterProvider>` is mounted.
+This method is optional. The bridge calls it after every navigation. The matching
+and the loaders therefore stay correct, also when no `<RouterProvider>` is
+mounted.
+
+The real implementation returns a promise. `watchRouterChanges` waits for that
+promise before it synchronizes the actor, because `router.load()` is the only
+public point that also runs `router.updateLatestLocation()`. See
+`watchRouterChanges` for the reason. A test double may return `void`, and the
+bridge then synchronizes synchronously.
 
 #### Returns
 
@@ -88,14 +128,22 @@ also when no `<RouterProvider>` is mounted.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L38)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L48)
+
+Navigates to a location. `search` carries the query of the target.
+
+The bridge passes `search` whenever the route of the actor holds a query. A
+`navigate({ to })` call with no `search` makes TanStack rebuild the query from
+`validateSearch({})` of the matched route, and a route that injects a default
+then commits a different href than the bridge asked for.
 
 #### Parameters
 
-| Parameter | Type                  |
-| --------- | --------------------- |
-| `args`    | \{ `to`: `string`; \} |
-| `args.to` | `string`              |
+| Parameter      | Type                                                              |
+| -------------- | ----------------------------------------------------------------- |
+| `args`         | \{ `search?`: `Record`\<`string`, `unknown`\>; `to`: `string`; \} |
+| `args.search?` | `Record`\<`string`, `unknown`\>                                   |
+| `args.to`      | `string`                                                          |
 
 #### Returns
 

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

@@ -6,7 +6,7 @@
 const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L60)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L60)
 
 Connects a `PlayerActor` to TanStack React Router. It keeps the actor state and the
 browser URL in step, in both directions.
@@ -26,9 +26,9 @@ connect), and the bridge supports this.
 
 ## Parameters
 
-| Parameter           | Type                                                                                                                                                     |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `__namedParameters` | [`PlayRouterProviderBaseProps`](../interfaces/PlayRouterProviderBaseProps.md)\<[`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md), `TActor`\> |
+| Parameter           | Type                                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `__namedParameters` | [`PlayRouterProviderBaseProps`](../type-aliases/PlayRouterProviderBaseProps.md)\<[`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md), `TActor`\> |
 
 ## Returns
 

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

@@ -4,7 +4,7 @@
 
 Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-router)
 
 TanStack Router gives React and Solid the same `navigate`, `load`, and `history`
 surface. Therefore the complete bridge implementation lives here, in
@@ -53,6 +53,24 @@ bridge.connect();
 bridge.disconnect();
 ```
 
+## Corrective navigation and a mounted `<RouterProvider>`
+
+The bridge subscribes to `router.history`, and it calls `router.load()` for every
+history event. The bridge waits for that `load()` promise before it synchronizes
+the actor. The wait is necessary for a mounted `<RouterProvider>`: its
+`Transitioner` component defers `router.updateLatestLocation()` into the
+`startTransition` of the framework. Without the wait, `router.latestLocation`
+still holds the previous href while the bridge runs. A corrective navigation for a
+refused URL then looks like a navigation to the same URL, and `commitLocation` of
+TanStack writes nothing to the browser history. The refused URL then stays in the
+address bar. With the wait, `router.latestLocation` is current, and the correction
+reaches the history. The bridge therefore works with a mounted `<RouterProvider>`
+and also without one.
+
+A burst of history events keeps its order: each event takes a sequence number, and
+a deferred synchronization runs only while its number is still the newest one. A
+`disconnect()` call retires every synchronization that still waits.
+
 ## Exports
 
 - `TanStackRouterBridgeBase` — the concrete bridge base class. Use it directly, or make a subclass of it

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

@@ -2,7 +2,7 @@
 
 # Class: TanStackRouterBridgeBase
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L107)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L133)
 
 The shared TanStack Router adapter. It implements the RouterBridge protocol through RouterBridgeBase
 
@@ -55,20 +55,22 @@ return () => bridge.disconnect();
 new TanStackRouterBridgeBase(
    router,
    actor,
-   routeMap): TanStackRouterBridgeBase;
+   routeMap,
+   options?): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L117)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L151)
 
 Creates a TanStack Router bridge
 
 #### Parameters
 
-| Parameter  | Type                                                                 | Description                                               |
-| ---------- | -------------------------------------------------------------------- | --------------------------------------------------------- |
-| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)        | The TanStack Router instance from `createRouter`          |
-| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | The XMachines actor instance                              |
-| `routeMap` | [`TanStackRouteMapLike`](../type-aliases/TanStackRouteMapLike.md)    | The bidirectional map between the state IDs and the paths |
+| Parameter  | Type                                                                     | Description                                               |
+| ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)            | The TanStack Router instance from `createRouter`          |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)     | The XMachines actor instance                              |
+| `routeMap` | [`TanStackRouteMapLike`](../type-aliases/TanStackRouteMapLike.md)        | The bidirectional map between the state IDs and the paths |
+| `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) | -                                                         |
 
 #### Returns
 
@@ -78,6 +80,84 @@ Creates a TanStack Router bridge
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
 
+## Accessors
+
+### basePath
+
+#### Get Signature
+
+```ts
+get basePath(): string;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:195
+
+The resolved URL prefix that the machine of this bridge is mounted under, or `""`
+when the machine owns the complete router.
+
+##### Returns
+
+`string`
+
+The resolved URL prefix of the mount, or `""` when the machine owns the complete router.
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePath`](../../play-router/classes/RouterBridgeBase.md#basepath)
+
+---
+
+### basePathParams
+
+#### Get Signature
+
+```ts
+get basePathParams(): Readonly<Record<string, string>>;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:221
+
+The resolved values of the `:param` segments of the mount, or `{}` for a prefix
+without a param.
+
+These params belong to the HOST: the host wrote the prefix and resolved the
+values, and they describe the route of the host and not the route of the machine.
+They therefore travel in NO `play.route` event. The machine is authoritative over
+its own params, and `event.params` holds what the pattern of the machine
+declares, and nothing else.
+
+They live here instead, because a value that reached the actor on a navigation
+ALONE would go stale: `setBasePath()` can move the mount while the machine stays
+on the same route, no event goes out, and `event.params` would then contradict
+`basePath`. A read of this accessor cannot go stale.
+
+A machine that needs the identity of its host — a `machineId`, a tenant — takes
+it through the `input` of the actor, where it belongs: that identity decides
+WHICH machine runs, and it is not a param of a route inside the machine.
+
+##### Example
+
+```typescript
+bridge.basePath; // "/abc123/play"
+bridge.basePathParams; // { machineId: "abc123" }
+```
+
+##### Returns
+
+`Readonly`\<`Record`\<`string`, `string`\>\>
+
+The resolved values of the `:param` segments of the mount, or `{}` for a prefix
+without a param.
+
+These params belong to the HOST, so they travel in NO `play.route` event — the
+machine is authoritative over its own params. This accessor is therefore the one
+way a host reads them back, and it cannot go stale: `setBasePath()` can move the
+mount while the machine stays on the same route, and no event goes out.
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/classes/RouterBridgeBase.md#basepathparams)
+
 ## Methods
 
 ### connect()
@@ -86,7 +166,7 @@ Creates a TanStack Router bridge
 connect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:124
+Defined in: play-router/dist/router-bridge-base.d.ts:313
 
 Connects the router bridge to the Actor.
 
@@ -96,7 +176,7 @@ in its own way.
 
 The order of these steps is part of the contract of the bridge:
 
-- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The constructor seeds `lastActorRoute` from `actor.currentRoute`, and it records no location
 - The method installs the actor watcher before the router subscriptions of the adapter
 - The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
 
@@ -120,7 +200,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:131
+Defined in: play-router/dist/router-bridge-base.d.ts:347
 
 Disconnects the router bridge from the Actor.
 
@@ -134,3 +214,65 @@ framework.
 #### Inherited from
 
 [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
+
+---
+
+### setBasePath()
+
+```ts
+setBasePath(basePath?, basePathParams?): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:258
+
+Moves the machine to a different mount point, while it stays connected.
+
+This is the "load and unload" half of a shared router. It moves WHERE an actor is
+mounted, and never WHICH actor is mounted: the actor, the route map, and its LRU
+cache all stay, and nothing goes away.
+
+An actor never changes identity. A prefix that IDENTIFIES the actor — a
+`machineId` that names the document it runs — therefore never moves through this
+method: a new identity is a new actor, and a new actor takes a new bridge, because
+`connect()` permits one bridge for each actor. The segments that move here are the
+ones that LOCATE: a region, a locale, a tenant, a workspace slug.
+
+The call then brings the location in step with the NEW prefix. A location inside
+the new mount runs the same first-synchronization decision as `connect()`: it
+drives the actor, and a restore keeps the route of the actor. A location OUTSIDE
+the new mount is the old mount in practice, so the bridge writes the new one
+itself, and it keeps the route of the actor while it does so — nothing else moves
+the address bar. A call that resolves to the current prefix changes no location,
+and it therefore reconciles nothing.
+
+#### Parameters
+
+| Parameter         | Type                                       | Description                                                                                                                                                      |
+| ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `basePath?`       | `string`                                   | The new prefix, as a pattern or as a concrete path. An absent value, `""`, and `"/"` all remove the prefix, and they give the machine the complete router again. |
+| `basePathParams?` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of `basePath`.                                                                                                               |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+For a prefix that resolves to one concrete path never.
+
+#### Throws
+
+When a `:param` of the prefix has no value.
+
+#### Example
+
+```typescript
+// The host moved this actor to another place in its URL space. `machineId` names
+// WHICH document the actor runs, and it does not change: a new identity is a new
+// actor, and therefore a new bridge, because one actor takes one bridge.
+bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
+```
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/classes/RouterBridgeBase.md#setbasepath)

package/api/@xmachines/play-tanstack-router/type-aliases/TanStackRouteMapLike.md

@@ -6,7 +6,7 @@
 type TanStackRouteMapLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L69)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L95)
 
 The narrow route-map surface that `TanStackRouterBridgeBase` requires.
 `RouteMap` from `@xmachines/play-router` satisfies it. The bridge converts a
@@ -24,7 +24,7 @@ that holds one form only still resolves the path.
 getPathByStateId(id): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L97)
 
 #### Parameters
 
@@ -44,7 +44,7 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https:/
 getStateIdByPath(path): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L70)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L96)
 
 #### Parameters
 

package/api/@xmachines/play-tanstack-router/type-aliases/TanStackRouterLike.md

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L39)
 
 The type-only interface of the TanStack Router surface that
 `TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
@@ -20,7 +20,7 @@ instance of `@tanstack/solid-router` both satisfy it.
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L46)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L72)
 
 #### location
 
@@ -61,6 +61,40 @@ subscribe(handler): () => void;
 
 () => `void`
 
+---
+
+### options?
+
+```ts
+optional options?: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L58)
+
+The options of the router. The bridge reads `parseSearch` only.
+
+TanStack owns the encoding of a query: its default `stringifySearch` writes each
+value through `JSON.stringify`, so a plain string arrives in the URL with quotes
+around it. `parseSearch` is the inverse, and it is therefore the only correct way
+to turn a query string of the URL into the `search` object that `navigate`
+accepts. A router double may hold neither.
+
+#### parseSearch()?
+
+```ts
+optional parseSearch(search): Record<string, unknown>;
+```
+
+##### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `search`  | `string` |
+
+##### Returns
+
+`Record`\<`string`, `unknown`\>
+
 ## Methods
 
 ### load()?
@@ -69,12 +103,18 @@ subscribe(handler): () => void;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L45)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 Runs the TanStack route matching and the loaders again for the current location.
-This method is optional. The bridge calls it after every navigation, and it does
-not wait for the result. The matching and the loaders therefore stay correct,
-also when no `<RouterProvider>` is mounted.
+This method is optional. The bridge calls it after every navigation. The matching
+and the loaders therefore stay correct, also when no `<RouterProvider>` is
+mounted.
+
+The real implementation returns a promise. `watchRouterChanges` waits for that
+promise before it synchronizes the actor, because `router.load()` is the only
+public point that also runs `router.updateLatestLocation()`. See
+`watchRouterChanges` for the reason. A test double may return `void`, and the
+bridge then synchronizes synchronously.
 
 #### Returns
 
@@ -88,14 +128,22 @@ also when no `<RouterProvider>` is mounted.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L38)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L48)
+
+Navigates to a location. `search` carries the query of the target.
+
+The bridge passes `search` whenever the route of the actor holds a query. A
+`navigate({ to })` call with no `search` makes TanStack rebuild the query from
+`validateSearch({})` of the matched route, and a route that injects a default
+then commits a different href than the bridge asked for.
 
 #### Parameters
 
-| Parameter | Type                  |
-| --------- | --------------------- |
-| `args`    | \{ `to`: `string`; \} |
-| `args.to` | `string`              |
+| Parameter      | Type                                                              |
+| -------------- | ----------------------------------------------------------------- |
+| `args`         | \{ `search?`: `Record`\<`string`, `unknown`\>; `to`: `string`; \} |
+| `args.search?` | `Record`\<`string`, `unknown`\>                                   |
+| `args.to`      | `string`                                                          |
 
 #### Returns
 

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

@@ -4,7 +4,7 @@
 
 **TanStack Solid Router adapter for XMachines Universal Player Architecture**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-solid-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-solid-router)
 
 This package integrates TanStack Solid Router with the TC39 Signals. The logic then drives the navigation through the Solid.js reactivity.
 
@@ -132,6 +132,7 @@ class TanStackSolidRouterBridge {
 - `disconnect()` — cancels the subscription to the history and stops all the synchronization.
 - It navigates with `router.navigate({ to: path })`.
 - It subscribes with `router.history.subscribe`. This covers PUSH, POP, BACK, FORWARD, REPLACE, and GO, and it works when no `<RouterProvider>` is mounted.
+- It waits for the `router.load()` of a history event before it synchronizes the actor. A mounted `<RouterProvider>` defers the refresh of `router.latestLocation`, and without the wait TanStack drops the corrective navigation for a refused URL. See the [`@xmachines/play-tanstack-router` README](../play-tanstack-router/README.md) for the details.
 
 ### `PlayRouterProvider`
 
@@ -328,7 +329,6 @@ MIT — see [LICENSE](LICENSE).
 
 - [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
-- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
@@ -337,6 +337,7 @@ MIT — see [LICENSE](LICENSE).
 ## Type Aliases
 
 - [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
+- [PlayRouterProviderBaseProps](type-aliases/PlayRouterProviderBaseProps.md)
 - [~~RoutableActor~~](type-aliases/RoutableActor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L105)
+Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L105)
 
 The shared base class of the route map for both directions.
 
@@ -58,7 +58,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L133)
+Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L133)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -87,7 +87,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L225)
+Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L229)
 
 Returns the path pattern of a state ID.
 
@@ -123,7 +123,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L185)
+Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L189)
 
 Resolves a URL path to its state ID.