@xmachines/docs 2.1.1 → 3.0.0

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

@@ -2,13 +2,28 @@
 
 # Class: ReactRouterBridge
 
-Defined in: [play-react-router/src/react-router-bridge.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/react-router-bridge.ts#L29)
+Defined in: [play-react-router/src/react-router-bridge.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/react-router-bridge.ts#L30)
 
-The abstract base class of every router adapter bridge of `@xmachines`.
+A `RouterBridge` whose machine is mounted at a URL prefix that can MOVE while the
+bridge stays connected.
 
-The class implements the RouterBridge protocol, and it holds every part of the
-bridge logic that the adapters share. A subclass implements the 3 abstract methods
-that are different in each framework, and it implements nothing more.
+Every bridge on `RouterBridgeBase` satisfies this interface. The interface exists
+so that a provider component moves a live bridge instead of a teardown of it: a
+host route that renders again with a new prefix keeps the actor, the route map, and
+its LRU cache.
+
+The mount that moves says WHERE an actor lives, and never WHICH actor lives there.
+An actor never changes identity, so a new identity is a new actor, and a new actor
+takes a new bridge.
+
+## 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 });
+```
 
 ## Extends
 
@@ -22,18 +37,20 @@ that are different in each framework, and it implements nothing more.
 new ReactRouterBridge(
    router,
    actor,
-   routeMap): ReactRouterBridge;
+   routeMap,
+   options?): ReactRouterBridge;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/react-router-bridge.ts#L32)
+Defined in: [play-react-router/src/react-router-bridge.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/react-router-bridge.ts#L33)
 
 #### Parameters
 
-| Parameter  | Type                                                                 |
-| ---------- | -------------------------------------------------------------------- |
-| `router`   | `Router`                                                             |
-| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) |
-| `routeMap` | [`RouteMap`](RouteMap.md)                                            |
+| Parameter  | Type                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| `router`   | `Router`                                                                 |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)     |
+| `routeMap` | [`RouteMap`](RouteMap.md)                                                |
+| `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) |
 
 #### Returns
 
@@ -43,6 +60,84 @@ Defined in: [play-react-router/src/react-router-bridge.ts:32](https://gitlab.com
 
 [`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/src/router-bridge-base.ts:255](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L255)
+
+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/src/router-bridge-base.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L284)
+
+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()
@@ -51,7 +146,7 @@ Defined in: [play-react-router/src/react-router-bridge.ts:32](https://gitlab.com
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L158)
+Defined in: [play-router/src/router-bridge-base.ts:506](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L506)
 
 Connects the router bridge to the Actor.
 
@@ -61,7 +156,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`
 
@@ -85,7 +180,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L270)
+Defined in: [play-router/src/router-bridge-base.ts:728](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L728)
 
 Disconnects the router bridge from the Actor.
 
@@ -99,3 +194,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/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L324)
+
+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-react-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.1/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/v3.0.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.1/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/v3.0.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.1/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/v3.0.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.1/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/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
 
 Resolves a URL path to its state ID.
 

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

@@ -6,19 +6,9 @@
 function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L83)
+Defined in: [play-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/create-play-router-provider.tsx#L52)
 
-Creates a React `PlayRouterProvider` component of one bridge class.
-
-The component of the return value connects a `PlayerActor` to the framework
-router. It keeps the actor state and the browser URL in step, in both directions.
-
-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 bridges support this.
+Builds a `PlayRouterProvider` for one React bridge class.
 
 ## Type Parameters
 
@@ -28,15 +18,14 @@ connect), and the bridges support this.
 
 ## Parameters
 
-| Parameter    | Type                                                                                         | Description                                                                            |
-| ------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | The bridge class. The provider builds it as `new BridgeCtor(router, actor, routeMap)`. |
+| Parameter    | Type                                                                                         | Description                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | The bridge class, built as `new BridgeCtor(router, actor, routeMap, options)`. |
 
 ## Returns
 
-A `PlayRouterProvider` component. It is generic over the actor type.
-Therefore the `renderer` callback receives the same concrete actor type as the
-prop.
+A `PlayRouterProvider` component, generic over the actor type, so the
+`renderer` callback receives the same concrete actor type as the prop.
 
 \<`TActor`\>(`__namedParameters`) => `Element`
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/create-route-map.ts#L47)
+Defined in: [play-router/src/create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L47)
 
 Creates a `RouteMap` from an XState state machine.
 

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

@@ -6,7 +6,7 @@
 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/v2.1.1/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/v3.0.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
 Creates a `RouteMap` from the node structure of a `RouteTree`.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayActor
 
-Defined in: [play-router/src/types.ts:312](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L312)
+Defined in: [play-router/src/types.ts:313](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L313)
 
 The complete actor shape of the `PlayRouterProvider` component of each framework
 adapter: `play-solid-router`, `play-vue-router`, `play-react-router`, and each
@@ -39,9 +39,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`\>                                        | The TC39 Signal of the current URL path of the actor, or of its state ID.                                                                                                                                                                | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:274](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L274) |
-| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | The TC39 Signal of the current view spec of the actor, or `null` when no view is active.                                                                                                                                                 | -                                                                                                                                                              | [play-router/src/types.ts:314](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L314) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route of the initial state of the machine. The constructor fixes it. A router bridge compares it with the browser URL. It therefore separates a deep link, where the router wins, from a restore of a session, where the actor wins. | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L280) |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | The TC39 Signal of the current URL path of the actor, or of its state ID.                                                                                                                                                                | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L275) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | The TC39 Signal of the current view spec of the actor, or `null` when no view is active.                                                                                                                                                 | -                                                                                                                                                              | [play-router/src/types.ts:315](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L315) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route of the initial state of the machine. The constructor fixes it. A router bridge compares it with the browser URL. It therefore separates a deep link, where the router wins, from a restore of a session, where the actor wins. | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:281](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L281) |
 
 ## Methods
 
@@ -51,7 +51,7 @@ function MyRouterProvider({ actor }: { actor: PlayActor }) {
 send(event): void;
 ```
 
-Defined in: [play-router/src/types.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L282)
+Defined in: [play-router/src/types.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L283)
 
 Sends a route navigation event to the actor.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L237)
+Defined in: [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L238)
 
 The routing event, with its parameters and its query
 
@@ -128,8 +128,8 @@ analysis of the pattern.
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
 | -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L242) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L240) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L241) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L239) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L238) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:243](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L243) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L241) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L242) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L240) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L239) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/play-router-provider.tsx#L27)
+Defined in: [play-react-router/src/play-router-provider.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/play-router-provider.tsx#L27)
 
 The props of the `PlayRouterProvider` of React Router.
 
@@ -12,7 +12,7 @@ The props of the `PlayRouterProvider` of React Router.
 
 ## Extends
 
-- [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md)\<`BrowserRouterInstance`, `TActor`\>
+- [`PlayRouterProviderBaseProps`](../type-aliases/PlayRouterProviderBaseProps.md)\<`BrowserRouterInstance`, `TActor`\>
 
 ## Type Parameters
 
@@ -22,9 +22,11 @@ The props of the `PlayRouterProvider` of React Router.
 
 ## Properties
 
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Inherited from                                                                                                                 | Defined in                                                                                                                                                                              |
-| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                         | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
-| <a id="property-router"></a> `router`     | `Router`                             | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                             | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L42) |
+| Property                                               | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Inherited from                               | Defined in                                                                                                                                              |
+| ------------------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                    | `TActor`                                   | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `PlayRouterProviderBaseProps.actor`          | [play-router/src/provider-lifecycle.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L42) |
+| <a id="property-basepath"></a> `basePath?`             | `string`                                   | Mounts the routes of the machine under a URL prefix that the host owns, so that the routes of the host and the routes of the machine share one router. `actor`, `router`, and `routeMap` each need a stable reference. This prop needs none, and it rebuilds the bridge never: a change moves the live bridge with `setBasePath()`, so a host route that renders again with a new prefix keeps the actor, the route map, and its cache. The prefix says WHERE an actor is mounted, and never WHICH actor is mounted. An actor never changes identity, so a prefix segment that IDENTIFIES the actor gives a different `actor` prop instead, and THAT rebuilds the bridge — which is correct, because one actor takes one bridge. A location outside the prefix belongs completely to the host: the bridge sends no event there, and it corrects no URL there. Every `:param` needs a value. An unresolved one throws a `MissingBasePathParamError` out of the mount effect, because the bridge writes no URL without it. Render this component only after the host holds the value, which a route loader or a `useParams()` call does already. | `PlayRouterProviderBaseProps.basePath`       | [play-router/src/provider-lifecycle.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L80) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [PlayRouterProviderBaseProps.basePath](#property-basepath), for example `{ machineId }` for `basePath="/:machineId/play"`. An inline object literal is correct here: the provider compares this prop by value, and a move to the same prefix does nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `PlayRouterProviderBaseProps.basePathParams` | [play-router/src/provider-lifecycle.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L89) |
+| <a id="property-renderer"></a> `renderer`              | (`actor`, `router`) => `ReactNode`         | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `PlayRouterProviderBaseProps.renderer`       | [play-router/src/provider-lifecycle.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L91) |
+| <a id="property-routemap"></a> `routeMap`              | [`RouteMap`](../classes/RouteMap.md)       | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `PlayRouterProviderBaseProps.routeMap`       | [play-router/src/provider-lifecycle.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L57) |
+| <a id="property-router"></a> `router`                  | `Router`                                   | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `PlayRouterProviderBaseProps.router`         | [play-router/src/provider-lifecycle.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L44) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L9)
 
 The options of `createRouteMap` and of `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 | Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
 | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/create-route-map.ts#L21) |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L21) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/base-route-map.ts#L54)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L54)
 
 One entry of the map between a state ID and a path.
 
@@ -24,5 +24,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
 | --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/base-route-map.ts#L58) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/base-route-map.ts#L56) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L56) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L358)
+Defined in: [play-router/src/types.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L359)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
@@ -56,7 +56,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L375)
+Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L376)
 
 Connects the router bridge to the Actor
 
@@ -86,7 +86,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L391)
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L392)
 
 Disconnects the router bridge from the Actor
 

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

@@ -3,13 +3,18 @@
 # Type Alias: PlayRouterBridgeConstructor\<TRouter\>
 
 ```ts
-type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap, options?) => RouterBridge;
 ```
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L20)
+Defined in: [play-router/src/provider-lifecycle.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L103)
 
-The constructor shape that a bridge class must satisfy for
-`createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
+The constructor shape that a bridge class must satisfy for a provider factory: `(router, actor, routeMap, options?) → RouterBridge`.
+
+The return type is `RouterBridge`, the published contract of a bridge, so a
+consumer bridge of its own keeps compiling. Every bridge on `RouterBridgeBase` also
+satisfies `MountableRouterBridge`, and the provider finds that mount API at run
+time: a bridge without it ignores `basePath`, exactly as it did before the option
+existed.
 
 ## Type Parameters
 
@@ -19,11 +24,12 @@ The constructor shape that a bridge class must satisfy for
 
 ## Parameters
 
-| Parameter  | Type                                      |
-| ---------- | ----------------------------------------- |
-| `router`   | `TRouter`                                 |
-| `actor`    | [`PlayActor`](../interfaces/PlayActor.md) |
-| `routeMap` | [`RouteMap`](../classes/RouteMap.md)      |
+| Parameter  | Type                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| `router`   | `TRouter`                                                                |
+| `actor`    | [`PlayActor`](../interfaces/PlayActor.md)                                |
+| `routeMap` | [`RouteMap`](../classes/RouteMap.md)                                     |
+| `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) |
 
 ## Returns