@xmachines/docs 2.1.1 → 3.0.0

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

@@ -2,7 +2,7 @@
 
 # Class: SolidRouterBridge
 
-Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/solid-router-bridge.ts#L58)
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-solid-router/src/solid-router-bridge.ts#L71)
 
 The SolidJS Router integration bridge. It extends RouterBridgeBase
 
@@ -11,10 +11,16 @@ reactive primitives of Solid. The actor-to-router direction uses the TC39 Signal
 watcher of the base class. The router-to-actor direction uses the Solid
 createEffect function for a native reactivity.
 
-The bridge reads each path parameter from the reactive `useParams()` proxy of
-Solid. It does not parse the URL again with URLPattern. Therefore a
-parameterized route works without the URLPattern polyfill, because the router of
-Solid holds the values already.
+The bridge prefers the values of the reactive `useParams()` proxy of Solid, so a
+parameterized route reaches URLPattern for its params never while Solid answers for
+it. Two cases still reach it: a bridge under a `basePath`, where Solid matched a route
+of the HOST and its params describe the route of the machine never, and a location
+that fills a segment of the pattern while Solid reports none of its names.
+
+This is about the CALLS, and not about the polyfill. A `RouteMap` that holds one
+parameterized route compiles it in the constructor and throws there without
+URLPattern, so an application with such a route needs the polyfill whatever this
+bridge does. See the `extractParams` override of this class.
 
 ## Extends
 
@@ -30,10 +36,11 @@ new SolidRouterBridge(
    location,
    params,
    actor,
-   routeMap): SolidRouterBridge;
+   routeMap,
+   options?): SolidRouterBridge;
 ```
 
-Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/solid-router-bridge.ts#L81)
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-solid-router/src/solid-router-bridge.ts#L94)
 
 Creates a SolidJS Router bridge
 
@@ -41,13 +48,14 @@ Creates a SolidJS Router bridge
 
 #### Parameters
 
-| Parameter       | Type                                                                 | Description                                                                                                                                                      |
-| --------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `solidNavigate` | `Navigator`                                                          | The result of the useNavigate() hook                                                                                                                             |
-| `location`      | [`LocationLike`](../../play-router/interfaces/LocationLike.md)       | The result of the useLocation() hook                                                                                                                             |
-| `params`        | `Params`                                                             | The result of the useParams() hook. The bridge reads each path parameter directly from it. A parameterized route therefore does not need the URLPattern polyfill |
-| `actor`         | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | The XMachines actor instance                                                                                                                                     |
-| `routeMap`      | [`RouteMap`](RouteMap.md)                                            | The bidirectional map between the state IDs and the paths                                                                                                        |
+| Parameter       | Type                                                                     | Description                                                                                                                                                      |
+| --------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `solidNavigate` | `Navigator`                                                              | The result of the useNavigate() hook                                                                                                                             |
+| `location`      | [`LocationLike`](../../play-router/interfaces/LocationLike.md)           | The result of the useLocation() hook                                                                                                                             |
+| `params`        | `Params`                                                                 | The result of the useParams() hook. The bridge reads each path parameter directly from it. A parameterized route therefore does not need the URLPattern polyfill |
+| `actor`         | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)     | The XMachines actor instance                                                                                                                                     |
+| `routeMap`      | [`RouteMap`](RouteMap.md)                                                | The bidirectional map between the state IDs and the paths                                                                                                        |
+| `options?`      | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) | -                                                                                                                                                                |
 
 #### Returns
 
@@ -57,6 +65,84 @@ Creates a SolidJS 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: [packages/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: [packages/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()
@@ -65,7 +151,7 @@ Creates a SolidJS Router bridge
 connect(): void;
 ```
 
-Defined in: [packages/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: [packages/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.
 
@@ -75,7 +161,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`
 
@@ -99,7 +185,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [packages/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: [packages/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.
 
@@ -122,7 +208,7 @@ framework.
 dispose(): void;
 ```
 
-Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/solid-router-bridge.ts#L202)
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-solid-router/src/solid-router-bridge.ts#L256)
 
 Disposes of the bridge. This method is the alias of disconnect.
 
@@ -139,3 +225,65 @@ onCleanup(() => bridge.dispose());
 #### Deprecated
 
 Use [disconnect](#disconnect). Will be removed in the next major.
+
+---
+
+### setBasePath()
+
+```ts
+setBasePath(basePath?, basePathParams?): void;
+```
+
+Defined in: [packages/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-solid-router/functions/createPlayRouterProvider.md

@@ -6,18 +6,9 @@
 function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(props) => any;
 ```
 
-Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L69)
+Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-solid-router/src/create-play-router-provider.tsx#L51)
 
-Creates a Solid `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 synchronously, during its own evaluation, because
-this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
-when Solid disposes of the component. React is different: the stability of a prop
-is no concern here, because the `props` accessor of Solid is reactive already, and
-the component creates the bridge one time for each of its instances.
+Builds a `PlayRouterProvider` for one Solid bridge class.
 
 ## Type Parameters
 
@@ -27,20 +18,19 @@ the component creates the bridge one time for each of its instances.
 
 ## 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`\>(`props`) => `any`
 
 ## Example
 
 ```tsx
-export const PlayRouterProvider = createPlayRouterProvider(MySolidRouterBridge);
+export const PlayRouterProvider = createPlayRouterProvider(SolidRouterBridge);
 ```

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [packages/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: [packages/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-solid-router/interfaces/AbstractActor.md

@@ -2,7 +2,7 @@
 
 # Abstract Interface: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-actor/src/abstract-actor.ts#L197)
+Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/abstract-actor.ts#L197)
 
 The abstract base class of an actor of the Play Architecture.
 
@@ -40,7 +40,7 @@ then answers from that empty actor, until you forward each one: `system`,
 | <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                                         | `Actor.ref`       | -                                                                                                                                                        |
 | <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                                       | `Actor.sessionId` | -                                                                                                                                                        |
 | <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                                         | `Actor.src`       | -                                                                                                                                                        |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor. | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-actor/src/abstract-actor.ts#L207) |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor. | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/abstract-actor.ts#L207) |
 | <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                   | `Actor.system`    | -                                                                                                                                                        |
 | <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                                         | `Actor.systemId`  | -                                                                                                                                                        |
 
@@ -211,7 +211,7 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-actor/src/abstract-actor.ts#L223)
+Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/abstract-actor.ts#L223)
 
 Sends an event to the Actor.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayActor
 
-Defined in: [packages/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: [packages/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) | [packages/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.                                                                                                                                                 | -                                                                                                                                                              | [packages/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) | [packages/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) | [packages/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.                                                                                                                                                 | -                                                                                                                                                              | [packages/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) | [packages/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: [packages/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: [packages/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-solid-router/interfaces/PlayRouteEvent.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [packages/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: [packages/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`                      | [packages/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`\> | [packages/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`\> | [packages/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`                       | [packages/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"`                 | [packages/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`                      | [packages/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`\> | [packages/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`\> | [packages/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`                       | [packages/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"`                 | [packages/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-solid-router/interfaces/PlayRouterProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [packages/play-solid-router/src/play-router-provider.tsx:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/play-router-provider.tsx#L50)
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-solid-router/src/play-router-provider.tsx#L50)
 
 The props of the `PlayRouterProvider` of Solid Router.
 
@@ -12,7 +12,7 @@ both directions. Take them from `useNavigate()`, from `useLocation()`, and from
 
 ## Extends
 
-- [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md)\<[`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md), `TActor`\>
+- [`PlayRouterProviderBaseProps`](../type-aliases/PlayRouterProviderBaseProps.md)\<[`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md), `TActor`\>
 
 ## Type Parameters
 
@@ -22,9 +22,11 @@ both directions. Take them from `useNavigate()`, from `useLocation()`, and from
 
 ## Properties
 
-| Property                                  | Type                                                      | Description                                                                         | Inherited from                                                                                                                 | Defined in                                                                                                                                                                                       |
-| ----------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <a id="property-actor"></a> `actor`       | `TActor`                                                  | The actor to keep in step with the router.                                          | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [packages/play-solid-router/src/create-play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L38) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `any`                              | The renderer callback receives the same concrete actor type as the prop.            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [packages/play-solid-router/src/create-play-router-provider.tsx:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L44) |
-| <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. | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [packages/play-solid-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L42) |
-| <a id="property-router"></a> `router`     | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | The router that the bridge keeps in step with the actor.                            | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [packages/play-solid-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L40) |
+| 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`          | [packages/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`       | [packages/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](../../play-react-router/interfaces/PlayRouterProviderProps.md#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` | [packages/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`) => `any`                              | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `PlayRouterProviderBaseProps.renderer`       | [packages/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`       | [packages/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`                  | [`SolidRouterHooks`](../type-aliases/SolidRouterHooks.md) | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `PlayRouterProviderBaseProps.router`         | [packages/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-solid-router/interfaces/RouteMapOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [packages/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: [packages/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`. | [packages/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`. | [packages/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-solid-router/interfaces/RouteMapping.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [packages/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: [packages/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?"` | [packages/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"`                          | [packages/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?"` | [packages/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"`                          | [packages/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-solid-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [packages/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: [packages/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: [packages/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: [packages/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: [packages/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: [packages/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-solid-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -3,17 +3,18 @@
 # Type Alias: PlayRouterBridgeConstructor\<TRouter\>
 
 ```ts
-type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap, options?) => RouterBridge;
 ```
 
-Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-solid-router/src/create-play-router-provider.tsx#L24)
+Defined in: [packages/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`.
 
-A bridge with another constructor shape, for example `SolidRouterBridge`, which
-takes each hook result as a separate argument, receives a thin subclass. That
-subclass packs the `router` prop again.
+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
 
@@ -23,11 +24,12 @@ subclass packs the `router` prop again.
 
 ## 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