@xmachines/docs 2.1.1 → 3.0.0

package/api/@xmachines/play-router/classes/RouterBridgeBase.md

@@ -2,13 +2,28 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L99)
+Defined in: [play-router/src/router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L112)
 
-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 });
+```
 
 ## Extended by
 
@@ -23,31 +38,113 @@ that are different in each framework, and it implements nothing more.
 
 ## Implements
 
-- [`RouterBridge`](../interfaces/RouterBridge.md)
+- [`MountableRouterBridge`](../interfaces/MountableRouterBridge.md)
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
+new RouterBridgeBase(
+   actor,
+   routeMap,
+   options?): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L127)
+Defined in: [play-router/src/router-bridge-base.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L230)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                          |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | The route map of both directions, for the resolution between a `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A framework adapter usually wraps the result of `createRouteMap(machine)`, or an equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the bare form `"stateId"`. The bridge tries both forms. Therefore an implementation of your own, for example a plain test object, handles one form only. |
-| `routeMap.getPathByStateId` | -                                                                                                                   |
-| `routeMap.getStateIdByPath` | -                                                                                                                   |
+| Parameter                    | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `actor`                      | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `routeMap`                   | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | The route map of both directions, for the resolution between a `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A framework adapter usually wraps the result of `createRouteMap(machine)`, or an equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the bare form `"stateId"`. The bridge tries both forms. Therefore an implementation of your own, for example a plain test object, handles one form only. |
+| `routeMap.getPathByStateId`  | -                                                                                                                   |
+| `routeMap.getStateIdByPath?` | -                                                                                                                   |
+| `options?`                   | [`BasePathOptions`](../interfaces/BasePathOptions.md)                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
 `RouterBridgeBase`
 
+## 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.
+
+#### Implementation of
+
+[`MountableRouterBridge`](../interfaces/MountableRouterBridge.md).[`basePath`](../interfaces/MountableRouterBridge.md#property-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.
+
+#### Implementation of
+
+[`MountableRouterBridge`](../interfaces/MountableRouterBridge.md).[`basePathParams`](../interfaces/MountableRouterBridge.md#property-basepathparams)
+
 ## Methods
 
 ### connect()
@@ -56,7 +153,7 @@ Defined in: [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [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.
 
@@ -66,7 +163,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`
 
@@ -80,7 +177,7 @@ An adapter that needs a different behavior of the first synchronization override
 
 #### Implementation of
 
-[`RouterBridge`](../interfaces/RouterBridge.md).[`connect`](../interfaces/RouterBridge.md#connect)
+[`MountableRouterBridge`](../interfaces/MountableRouterBridge.md).[`connect`](../interfaces/MountableRouterBridge.md#connect)
 
 ---
 
@@ -90,7 +187,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [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.
 
@@ -103,4 +200,66 @@ framework.
 
 #### Implementation of
 
-[`RouterBridge`](../interfaces/RouterBridge.md).[`disconnect`](../interfaces/RouterBridge.md#disconnect)
+[`MountableRouterBridge`](../interfaces/MountableRouterBridge.md).[`disconnect`](../interfaces/MountableRouterBridge.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 });
+```
+
+#### Implementation of
+
+[`MountableRouterBridge`](../interfaces/MountableRouterBridge.md).[`setBasePath`](../interfaces/MountableRouterBridge.md#setbasepath)

package/api/@xmachines/play-router/functions/buildPlayRouteEvent.md

@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [router-sync.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-sync.ts#L175)
+Defined in: [play-router/src/router-sync.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L175)
 
 Builds a normalized `play.route` event from the raw input of a router or of a
 browser.

package/api/@xmachines/play-router/functions/buildRouteTree.md

@@ -6,7 +6,7 @@
 function buildRouteTree(routes): RouteTree;
 ```
 
-Defined in: [build-tree.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/build-tree.ts#L22)
+Defined in: [play-router/src/build-tree.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/build-tree.ts#L22)
 
 Builds the hierarchical route tree from the flat list of the routes
 

package/api/@xmachines/play-router/functions/cleanFrameworkParams.md

@@ -0,0 +1,40 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / cleanFrameworkParams
+
+# Function: cleanFrameworkParams()
+
+```ts
+function cleanFrameworkParams(params): Record<string, string>;
+```
+
+Defined in: [play-router/src/framework-params.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/framework-params.ts#L182)
+
+The params of a framework router, in the shape that [pickOwnParams](pickOwnParams.md) reads.
+
+Every framework reports a param that its own route DECLARES and that the location
+did not fill: Vue Router gives `undefined` or `""`, and SolidJS Router does the
+same. Such an entry is not an answer, and a pick that kept it would send an empty
+value to the actor as though the path carried one. Drop it here instead, one time,
+because the rule belongs to the decision of [resolveFrameworkParams](resolveFrameworkParams.md) and not
+to a bridge: `VueRouterBridge` and `SolidRouterBridge` held one copy each.
+
+A value of an array — the splat of a catch-all route of Vue Router — becomes its
+`String()` form, exactly as a single value does.
+
+The result has a null prototype, for the same reason [pickOwnParams](pickOwnParams.md) gives: a
+plain `{}` accumulator turns `cleaned["__proto__"] = value` into a write of the
+PROTOTYPE setter, which drops a string value in silence. `pickOwnParams` then read
+`Object.hasOwn(params, "__proto__")` as `false`, called the pick incomplete, and fell
+back to the URLPattern extraction — which THROWS on a runtime with no URLPattern, for
+a route the framework had answered already.
+
+## Parameters
+
+| Parameter | Type                            | Description                             |
+| --------- | ------------------------------- | --------------------------------------- |
+| `params`  | `Record`\<`string`, `unknown`\> | The raw params of the framework router. |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+The params with no absent value, each one a string.

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

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

@@ -6,7 +6,7 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [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-router/functions/createRouterConnection.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouterConnection
+
+# Function: createRouterConnection()
+
+```ts
+function createRouterConnection(bridge): RouterConnection;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L303)
+
+Wraps a live bridge in the [RouterConnection](../interfaces/RouterConnection.md) that `connectRouter` returns.
+
+## Parameters
+
+| Parameter | Type                                                              | Description                                          |
+| --------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
+| `bridge`  | [`MountableRouterBridge`](../interfaces/MountableRouterBridge.md) | The bridge that `connectRouter` built and connected. |
+
+## Returns
+
+[`RouterConnection`](../interfaces/RouterConnection.md)

package/api/@xmachines/play-router/functions/detectDuplicateRoutes.md

@@ -6,7 +6,7 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/validate-routes.ts#L70)
+Defined in: [play-router/src/validate-routes.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/validate-routes.ts#L70)
 
 Finds each duplicate route path
 

package/api/@xmachines/play-router/functions/extractMachineRoutes.md

@@ -6,7 +6,7 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [extract-routes.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/extract-routes.ts#L92)
+Defined in: [play-router/src/extract-routes.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/extract-routes.ts#L92)
 
 Reads the complete route tree from the graph of a state machine
 

package/api/@xmachines/play-router/functions/extractQuery.md

@@ -6,7 +6,7 @@
 function extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-sync.ts#L155)
+Defined in: [play-router/src/router-sync.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L155)
 
 Parses a URL search string into the plain object that a `play.route` event
 needs.

package/api/@xmachines/play-router/functions/extractRouteParams.md

@@ -6,7 +6,7 @@
 function extractRouteParams(pathname, pattern): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-sync.ts#L117)
+Defined in: [play-router/src/router-sync.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L117)
 
 Reads the named path parameters of a URL, with the URLPattern API.
 

package/api/@xmachines/play-router/functions/findRouteById.md

@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/find-route.ts#L59)
+Defined in: [play-router/src/find-route.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/find-route.ts#L59)
 
 Finds a route node by its state ID
 

package/api/@xmachines/play-router/functions/findRouteByPath.md

@@ -6,7 +6,7 @@
 function findRouteByPath(tree, path): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/find-route.ts#L86)
+Defined in: [play-router/src/find-route.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/find-route.ts#L86)
 
 Finds a route node by its URL path
 

package/api/@xmachines/play-router/functions/getNavigableRoutes.md

@@ -6,7 +6,7 @@
 function getNavigableRoutes(tree, stateId): RouteNode[];
 ```
 
-Defined in: [query.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/query.ts#L41)
+Defined in: [play-router/src/query.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/query.ts#L48)
 
 Returns every route of a navigation from the given state
 

package/api/@xmachines/play-router/functions/getPatternParamNames.md

@@ -0,0 +1,24 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / getPatternParamNames
+
+# Function: getPatternParamNames()
+
+```ts
+function getPatternParamNames(pattern): string[];
+```
+
+Defined in: [play-router/src/framework-params.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/framework-params.ts#L27)
+
+Reads the names of every `:param` of a route pattern of the route map.
+
+## Parameters
+
+| Parameter | Type     | Description                                      |
+| --------- | -------- | ------------------------------------------------ |
+| `pattern` | `string` | A route pattern, for example `/profile/:userId`. |
+
+## Returns
+
+`string`[]
+
+The names, in the order that the pattern declares them. A fresh array, because
+`readPatternParams` caches the one it holds.

package/api/@xmachines/play-router/functions/getRequiredPatternParamNames.md

@@ -0,0 +1,36 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / getRequiredPatternParamNames
+
+# Function: getRequiredPatternParamNames()
+
+```ts
+function getRequiredPatternParamNames(pattern): string[];
+```
+
+Defined in: [play-router/src/framework-params.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/framework-params.ts#L85)
+
+The names of every param the pattern REQUIRES, so `:name?` is left out.
+
+An optional segment that did not match has no value, and a framework reports none.
+That is a complete answer and not a partial one, so a MIXED pattern such as
+`/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
+A caller that counted that absence as a gap would fall back to the URLPattern
+extraction, which THROWS on a runtime with no URLPattern — for a route the framework
+had already answered.
+
+A pattern whose params are ALL optional reports nothing at all, which reads the same
+as "the framework matched another route", so [pickOwnParams](pickOwnParams.md) falls back for it.
+[resolveFrameworkParams](resolveFrameworkParams.md) settles that case from the PATH instead, and it needs
+no URLPattern to do it.
+
+## Parameters
+
+| Parameter | Type     | Description                                            |
+| --------- | -------- | ------------------------------------------------------ |
+| `pattern` | `string` | A route pattern, for example `/profile/:userId/:tab?`. |
+
+## Returns
+
+`string`[]
+
+The required names, in the order that the pattern declares them. A fresh
+array, because `readPatternParams` caches the one it holds.

package/api/@xmachines/play-router/functions/getRoutableRoutes.md

@@ -6,7 +6,7 @@
 function getRoutableRoutes(tree): RouteNode[];
 ```
 
-Defined in: [query.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/query.ts#L106)
+Defined in: [play-router/src/query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/query.ts#L113)
 
 Returns every route of the tree that has a route, in one flat array
 

package/api/@xmachines/play-router/functions/getRouteMappings.md

@@ -0,0 +1,67 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / getRouteMappings
+
+# Function: getRouteMappings()
+
+```ts
+function getRouteMappings(tree, options?): RouteMapping[];
+```
+
+Defined in: [play-router/src/query.ts:250](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/query.ts#L250)
+
+Returns the `{ stateId, path }` entries that a host router needs, so that it can
+register the routes of a machine under a base path, and remove them again later.
+
+This function makes the routes dynamic. `getStateIdByPath` and `getPathByStateId`
+answer the question "what is this URL?" at the moment of a navigation, but a host
+that declares real route objects — a route tree of TanStack, a `RouteObject[]`, an
+`addRoute` call of vue-router — needs the LIST in advance, and it needs that list
+with the prefix of the mount. A registration of these paths, and a removal of them
+when the machine unloads, keeps the route table of the host in step with the mount.
+
+`basePathParams` decides the form of each path, and both forms are useful:
+
+- **Given** → a concrete path (`/abc123/play/profile/:userId`), for a route that
+  the host adds at run time, after a loader resolved the mount.
+- **Absent** → the pattern stays (`/:machineId/play/profile/:userId`), for a static
+  route declaration of the host.
+
+The function ALWAYS keeps each `:param` segment that the machine declares itself:
+those are the params that the route of the host must match.
+
+## Parameters
+
+| Parameter  | Type                                                  | Description                                                                                                                                                                                                                                                                                              |
+| ---------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tree`     | [`RouteTree`](../interfaces/RouteTree.md)             | The route tree of extractMachineRoutes()                                                                                                                                                                                                                                                                 |
+| `options?` | [`BasePathOptions`](../interfaces/BasePathOptions.md) | The optional `{ basePath, basePathParams }`, the same option as the bridge takes. Each `stateId` comes from the route tree, so it carries NO `#` prefix. A host that keys its route table on the target of a `play.route` event adds the `#` itself, because the event always carries the prefixed form. |
+
+## Returns
+
+[`RouteMapping`](../interfaces/RouteMapping.md)[]
+
+One entry for each state with a route, in the order of the route tree.
+
+## Throws
+
+For a base path that resolves to one concrete path never.
+
+## Throws
+
+When `basePathParams` is present and it omits a `:param`.
+
+## Example
+
+```typescript
+const tree = extractMachineRoutes(machine);
+
+// Concrete, for a route that the host adds after a loader resolved the mount
+getRouteMappings(tree, { basePath: "/:machineId/play", basePathParams: { machineId: "abc123" } });
+// [
+//   { stateId: "app.home",    path: "/abc123/play" },
+//   { stateId: "app.profile", path: "/abc123/play/profile/:userId" },
+// ]
+
+// The pattern, for a static route declaration of the host
+getRouteMappings(tree, { basePath: "/:machineId/play" });
+// [{ stateId: "app.home", path: "/:machineId/play" }, ...]
+```

package/api/@xmachines/play-router/functions/getTransitionReachableRoutes.md

@@ -6,7 +6,7 @@
 function getTransitionReachableRoutes(graph, stateId): string[];
 ```
 
-Defined in: [query.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/query.ts#L158)
+Defined in: [play-router/src/query.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/query.ts#L165)
 
 Returns the routes that a transition from the current state can reach
 

package/api/@xmachines/play-router/functions/isMountableBridge.md

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / isMountableBridge
+
+# Function: isMountableBridge()
+
+```ts
+function isMountableBridge(bridge): bridge is MountableRouterBridge;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L118)
+
+Tells you whether a bridge can move its mount.
+
+[PlayRouterBridgeConstructor](../type-aliases/PlayRouterBridgeConstructor.md) asks for a `RouterBridge`, the published
+contract, so a consumer bridge that never heard of `basePath` still compiles. Such a
+bridge ignores the prefix, exactly as it did before the option existed, so the probe
+runs at run time rather than in the type system.
+
+## Parameters
+
+| Parameter | Type                                                                     |
+| --------- | ------------------------------------------------------------------------ |
+| `bridge`  | [`RouterBridge`](../interfaces/RouterBridge.md) \| `null` \| `undefined` |
+
+## Returns
+
+`bridge is MountableRouterBridge`

package/api/@xmachines/play-router/functions/isRouteReachable.md

@@ -6,7 +6,7 @@
 function isRouteReachable(graph, fromStateId, toStateId): boolean;
 ```
 
-Defined in: [query.ts:186](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/query.ts#L186)
+Defined in: [play-router/src/query.ts:193](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/query.ts#L193)
 
 Tells you if a transition from the current state can reach a route