@xmachines/docs 2.0.0 → 2.1.1

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

@@ -6,11 +6,11 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L38)
 
-Structural (type-only) interface for the TanStack Router surface used by
-`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
-`@tanstack/solid-router` instances satisfy it.
+The type-only interface of the TanStack Router surface that
+`TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
+instance of `@tanstack/solid-router` both satisfy it.
 
 ## Properties
 
@@ -20,7 +20,7 @@ Structural (type-only) interface for the TanStack Router surface used by
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 #### location
 
@@ -28,9 +28,10 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https:/
 location: object;
 ```
 
-Current location — populated from `window.location` when `createRouter()` runs,
-before `router.load()`. Always available in the browser.
-`router.state.location` is only populated after `router.load()` and may be stale.
+The current location. `createRouter()` fills it from `window.location`, before
+`router.load()`. It is always available in the browser.
+`router.state.location` has a value only after `router.load()`, and that value
+can be old.
 
 ##### location.pathname
 
@@ -60,6 +61,40 @@ subscribe(handler): () => void;
 
 () => `void`
 
+---
+
+### options?
+
+```ts
+optional options?: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L57)
+
+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()?
@@ -68,11 +103,18 @@ subscribe(handler): () => void;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L70)
+
+Runs the TanStack route matching and the loaders again for the current location.
+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.
 
-Re-runs TanStack route matching and loaders for the current location.
-Optional: the bridge calls it (fire-and-forget) after every navigation so
-matching/loaders stay in sync even without a mounted `<RouterProvider>`.
+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
 
@@ -86,14 +128,22 @@ matching/loaders stay in sync even without a mounted `<RouterProvider>`.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L47)
+
+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,16 +6,17 @@
 const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L57)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-react-router/src/play-router-provider.tsx#L60)
 
-Connects a `PlayerActor` to TanStack React Router, keeping actor state and
-browser URL in sync bidirectionally.
+Connects a `PlayerActor` to TanStack React Router. It keeps the actor state and the
+browser URL in step, in both directions.
 
-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 bridge supports.
+The component creates the bridge one time, on mount, and it disconnects the bridge
+on unmount. It also builds the bridge again on a change of the identity of `actor`,
+of `router`, or of `routeMap`. Therefore all three props must be **stable
+references**: create them outside the JSX, or hold them with `useMemo`. Under the
+React `<StrictMode>`, the effect runs two times on mount (connect, disconnect,
+connect), and the bridge supports this.
 
 ## Type Parameters
 

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

@@ -4,16 +4,16 @@
 
 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.0.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.1.1-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-router)
 
-TanStack Router exposes the identical `navigate` / `load` / `history` surface in
-both its React and Solid flavours, so the entire bridge implementation lives here
-as `TanStackRouterBridgeBase` (extending `RouterBridgeBase` from
-[`@xmachines/play-router`](../play-router/README.md)). The framework adapter
-packages only subclass it to bind their concrete router type.
+TanStack Router gives React and Solid the same `navigate`, `load`, and `history`
+surface. Therefore the complete bridge implementation lives here, in
+`TanStackRouterBridgeBase`. That class extends `RouterBridgeBase` from
+[`@xmachines/play-router`](../play-router/README.md). Each framework adapter
+package makes a subclass of it, and binds its own router type.
 
-This package has **no TanStack runtime dependency** — `TanStackRouterLike` is a
-structural, type-only interface covering the small router surface the bridge uses.
+This package has **no TanStack runtime dependency**. `TanStackRouterLike` is a
+type-only interface. It describes the small router surface that the bridge uses.
 
 ## Who consumes it
 
@@ -23,21 +23,59 @@ structural, type-only interface covering the small router surface the bridge use
 ## Usage
 
 ```typescript
+import { createMachine } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { createRouteMap } from "@xmachines/play-router";
 import { TanStackRouterBridgeBase } from "@xmachines/play-tanstack-router";
 
+const machine = createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+		},
+	}),
+);
+
+const actor = definePlayer({ machine })();
+actor.start();
+
+const routeMap = createRouteMap(machine);
+
 export class MyTanStackBridge extends TanStackRouterBridgeBase {}
 
+// router: your TanStack Router instance (from the React or Solid createRouter)
 const bridge = new MyTanStackBridge(router, actor, routeMap);
 bridge.connect();
-// Cleanup on unmount
-return () => bridge.disconnect();
+// Disconnect the bridge at teardown
+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` — abstract bridge base class
-- `TanStackRouterLike` — structural (type-only) TanStack router surface
-- `TanStackRouteMapLike` — narrow route-map surface the bridge requires
+- `TanStackRouterBridgeBase` — the concrete bridge base class. Use it directly, or make a subclass of it
+- `TanStackRouterLike` — the TanStack router surface, as a type-only interface
+- `TanStackRouteMapLike` — the narrow route-map surface that the bridge requires
 
 ## License
 
@@ -45,10 +83,10 @@ MIT
 
 @xmachines/play-tanstack-router
 
-Shared, framework-agnostic TanStack Router bridge base for XMachines Play.
-Consumed by `@xmachines/play-tanstack-react-router` and
-`@xmachines/play-tanstack-solid-router`, which subclass
-`TanStackRouterBridgeBase` to bind their concrete router type.
+The shared, framework-agnostic TanStack Router bridge base for XMachines Play.
+`@xmachines/play-tanstack-react-router` and
+`@xmachines/play-tanstack-solid-router` use it. Each of them makes a subclass of
+`TanStackRouterBridgeBase`, and the subclass binds its own router type.
 
 ## Classes
 

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

@@ -2,32 +2,34 @@
 
 # Class: TanStackRouterBridgeBase
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:132](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L132)
 
-Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
+The shared TanStack Router adapter. It implements the RouterBridge protocol through RouterBridgeBase
 
 ## Remarks
 
-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
-router.subscribe("onBeforeLoad") approach only works when TanStack's
-Transitioner component is mounted (i.e. inside a full <RouterProvider>).
-Since this bridge is used without <RouterProvider>, we must subscribe to
-the underlying history object directly — which is exactly what Transitioner
+The class extends RouterBridgeBase, and the base class does all the common
+lifecycle work and synchronization work. This class adds the TanStack navigation
+methods and subscription methods that the React adapter and the Solid adapter
+share.
+
+The bridge subscribes to router.history, not to
+router.subscribe("onBeforeLoad"). Therefore it also receives a browser BACK or
+FORWARD navigation, which is a popstate event. The
+router.subscribe("onBeforeLoad") method works only when the Transitioner
+component of TanStack is mounted, which means inside a complete
+<RouterProvider>. This bridge works without <RouterProvider>. Therefore it
+subscribes to the history object directly, and this is exactly what Transitioner
 does internally: `router.history.subscribe(router.load)`.
 
-Architectural Invariants:
+Architectural invariants:
 
-- INV-02 (Passive Infrastructure): Router reflects actor state, never decides
-- Actor validates all navigation via guards before URL changes
+- INV-02 (Passive Infrastructure): the router reflects the actor state. It never decides
+- The actor checks every navigation with its guards before the 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).
+The class is concrete. You can create an instance of it directly. Each framework
+package re-exports it, or makes a subclass of it, only to bind the public name of
+the adapter. The Solid package also adds the `dispose()` alias.
 
 ## Example
 
@@ -56,17 +58,17 @@ new TanStackRouterBridgeBase(
    routeMap): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L150)
 
-Create a TanStack Router bridge
+Creates a TanStack Router bridge
 
 #### Parameters
 
-| 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`](../type-aliases/TanStackRouteMapLike.md)    | Bidirectional mapping between state IDs and 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 |
 
 #### Returns
 
@@ -84,21 +86,23 @@ Create a TanStack Router bridge
 connect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:120
+Defined in: play-router/dist/router-bridge-base.d.ts:124
 
-Connect the router bridge to the Actor.
+Connects the router bridge to the Actor.
 
-Sets up the TC39 Signal watcher for actor → router direction and
-starts watching router changes (framework-specific).
+The method installs the TC39 Signal watcher of the direction from the actor to the
+router. It then starts the watch of the router changes, which each framework does
+in its own way.
 
-Ordering here is part of the bridge contract:
+The order of these steps is part of the contract of the bridge:
 
-- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
-- the actor watcher is installed before adapter router subscriptions
-- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- 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`
 
-Adapters that need custom initial-sync behavior should override
-`getInitialRouterPath()` rather than reordering `connect()` steps.
+An adapter that needs a different behavior of the first synchronization overrides
+`getInitialRouterPath()`. It does not change the order of the steps of
+`connect()`.
 
 #### Returns
 
@@ -116,11 +120,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: play-router/dist/router-bridge-base.d.ts:126
+Defined in: play-router/dist/router-bridge-base.d.ts:131
 
-Disconnect the router bridge from the Actor.
+Disconnects the router bridge from the Actor.
 
-Stops signal watching and unregisters framework-specific router listener.
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
 
 #### Returns
 

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

@@ -6,15 +6,15 @@
 type TanStackRouteMapLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L66)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L94)
 
-Narrow route-map surface required by `TanStackRouterBridgeBase`.
-`RouteMap` from `@xmachines/play-router` satisfies it (null returns are
-adapted to undefined internally).
+The narrow route-map surface that `TanStackRouterBridgeBase` requires.
+`RouteMap` from `@xmachines/play-router` satisfies it. The bridge converts a
+`null` result into `undefined` internally.
 
-`getPathByStateId` may receive the stateId in either `"#stateId"` or bare
-`"stateId"` form — the bridge tries both forms automatically, so custom
-implementations keyed on a single form still resolve.
+`getPathByStateId` can receive the stateId in the form `"#stateId"` or in the
+bare form `"stateId"`. The bridge tries both forms. Therefore an implementation
+that holds one form only still resolves the path.
 
 ## Methods
 
@@ -24,7 +24,7 @@ implementations keyed on a single form still resolve.
 getPathByStateId(id): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L68)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L96)
 
 #### Parameters
 
@@ -44,7 +44,7 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https:/
 getStateIdByPath(path): string | null | undefined;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L67)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L95)
 
 #### Parameters
 

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

@@ -6,11 +6,11 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L38)
 
-Structural (type-only) interface for the TanStack Router surface used by
-`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
-`@tanstack/solid-router` instances satisfy it.
+The type-only interface of the TanStack Router surface that
+`TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
+instance of `@tanstack/solid-router` both satisfy it.
 
 ## Properties
 
@@ -20,7 +20,7 @@ Structural (type-only) interface for the TanStack Router surface used by
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 #### location
 
@@ -28,9 +28,10 @@ Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https:/
 location: object;
 ```
 
-Current location — populated from `window.location` when `createRouter()` runs,
-before `router.load()`. Always available in the browser.
-`router.state.location` is only populated after `router.load()` and may be stale.
+The current location. `createRouter()` fills it from `window.location`, before
+`router.load()`. It is always available in the browser.
+`router.state.location` has a value only after `router.load()`, and that value
+can be old.
 
 ##### location.pathname
 
@@ -60,6 +61,40 @@ subscribe(handler): () => void;
 
 () => `void`
 
+---
+
+### options?
+
+```ts
+optional options?: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L57)
+
+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()?
@@ -68,11 +103,18 @@ subscribe(handler): () => void;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L70)
+
+Runs the TanStack route matching and the loaders again for the current location.
+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.
 
-Re-runs TanStack route matching and loaders for the current location.
-Optional: the bridge calls it (fire-and-forget) after every navigation so
-matching/loaders stay in sync even without a mounted `<RouterProvider>`.
+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
 
@@ -86,14 +128,22 @@ matching/loaders stay in sync even without a mounted `<RouterProvider>`.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L47)
+
+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