@xmachines/docs 2.2.0 → 4.0.0

package/api/@xmachines/play-router/{functions → index/functions}/buildRouteTree.md

@@ -1,12 +1,12 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / buildRouteTree
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / buildRouteTree
 
 # Function: buildRouteTree()
 
 ```ts
-function buildRouteTree(routes): RouteTree;
+function buildRouteTree<TGraph>(routes): RouteTree<TGraph>;
 ```
 
-Defined in: [build-tree.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/build-tree.ts#L22)
+Defined in: [packages/play-router/src/build-tree.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/build-tree.ts#L38)
 
 Builds the hierarchical route tree from the flat list of the routes
 
@@ -21,6 +21,16 @@ the same raw string below two different parents are valid, and two different raw
 strings that resolve to the same complete path are not: those two overwrite each
 other in `byPath` in silence.
 
+`TGraph` names the type of the graph that a CALLER attaches afterwards. The builder
+attaches none: it reads a list of routes and writes the maps of the tree.
+`extractMachineRoutes` of `@xmachines/play-router/xstate` binds it to `MachineGraph`.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `TGraph`       | `unknown`    |
+
 ## Parameters
 
 | Parameter | Type                                        | Description                                                 |
@@ -29,7 +39,7 @@ other in `byPath` in silence.
 
 ## Returns
 
-[`RouteTree`](../interfaces/RouteTree.md)
+[`RouteTree`](../interfaces/RouteTree.md)\<`TGraph`\>
 
 The RouteTree, with its root, its byStateId map, and its byPath map
 

package/api/@xmachines/play-router/{functions → index/functions}/cleanFrameworkParams.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / cleanFrameworkParams
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / cleanFrameworkParams
 
 # Function: cleanFrameworkParams()
 
@@ -6,7 +6,7 @@
 function cleanFrameworkParams(params): Record<string, string>;
 ```
 
-Defined in: [framework-params.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L182)
+Defined in: [packages/play-url/src/framework-params.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L148)
 
 The params of a framework router, in the shape that [pickOwnParams](pickOwnParams.md) reads.
 
@@ -24,8 +24,7 @@ The result has a null prototype, for the same reason [pickOwnParams](pickOwnPara
 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.
+back to the URLPattern extraction, for a route the framework had answered already.
 
 ## Parameters
 

package/api/@xmachines/play-router/{functions → index/functions}/createRouteMapFromTree.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromTree
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / createRouteMapFromTree
 
 # Function: createRouteMapFromTree()
 
@@ -6,12 +6,13 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [packages/play-router/src/create-route-map-from-tree.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/create-route-map-from-tree.ts#L40)
 
 Creates a `RouteMap` from the node structure of a `RouteTree`.
 
-A framework router adapter uses this function when it gives a `RouteTree` from
-`extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
+A framework router adapter uses this function when it holds a `RouteTree`, for example
+from `extractMachineRoutes()` of `@xmachines/play-router/xstate`, and not when it calls
+`createRouteMap()` of that package directly.
 
 The function walks every node, and it collects the pairs
 `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
@@ -19,6 +20,11 @@ absolute resolved path, for example `"/dashboard/overview"`, and `RouteMap` need
 that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
 same way, because it also uses `node.fullPath`.
 
+The walk SKIPS the synthetic root node. `buildRouteTree` makes that node to hold each
+absolute route, and no state of a machine declares it. `createRouteMap` skips it as
+well, through `getRoutableRoutes`, and the two functions therefore answer the same map
+for the same tree.
+
 ## Parameters
 
 | Parameter   | Type                                                  | Description                                                                                  |
@@ -36,11 +42,12 @@ A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ```typescript
 // The preferred form — one call for an XState machine:
-import { createRouteMap } from "@xmachines/play-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
 
 // The two-step form, for a framework adapter that works with a route tree:
-import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+import { createRouteMapFromTree } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
 ```

package/api/@xmachines/play-router/{functions → index/functions}/createRouterConnection.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouterConnection
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / createRouterConnection
 
 # Function: createRouterConnection()
 
@@ -6,7 +6,7 @@
 function createRouterConnection(bridge): RouterConnection;
 ```
 
-Defined in: [provider-lifecycle.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L284)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:313](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L313)
 
 Wraps a live bridge in the [RouterConnection](../interfaces/RouterConnection.md) that `connectRouter` returns.
 

package/api/@xmachines/play-router/{functions → index/functions}/detectDuplicateRoutes.md

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

package/api/@xmachines/play-router/{functions → index/functions}/extractQuery.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / extractQuery
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / extractQuery
 
 # Function: extractQuery()
 
@@ -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.2.0/packages/play-router/src/router-sync.ts#L155)
+Defined in: [packages/play-router/src/router-sync.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L163)
 
 Parses a URL search string into the plain object that a `play.route` event
 needs.

package/api/@xmachines/play-router/{functions → index/functions}/extractRouteParams.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / extractRouteParams
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / extractRouteParams
 
 # Function: extractRouteParams()
 
@@ -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.2.0/packages/play-router/src/router-sync.ts#L117)
+Defined in: [packages/play-router/src/router-sync.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L119)
 
 Reads the named path parameters of a URL, with the URLPattern API.
 
@@ -42,7 +42,7 @@ The record of the parameter values of the read, or `{}` for a static pattern.
 
 ## Throws
 
-When `URLPattern` is absent and the pattern holds a parameter.
+When URLPattern cannot compile the pattern.
 
 ## Example
 

package/api/@xmachines/play-router/{functions → index/functions}/findRouteById.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / findRouteById
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / findRouteById
 
 # Function: findRouteById()
 
@@ -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.2.0/packages/play-router/src/find-route.ts#L59)
+Defined in: [packages/play-router/src/find-route.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/find-route.ts#L56)
 
 Finds a route node by its state ID
 

package/api/@xmachines/play-router/{functions → index/functions}/findRouteByPath.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / findRouteByPath
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / findRouteByPath
 
 # Function: findRouteByPath()
 
@@ -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.2.0/packages/play-router/src/find-route.ts#L86)
+Defined in: [packages/play-router/src/find-route.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/find-route.ts#L83)
 
 Finds a route node by its URL path
 

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

@@ -0,0 +1,29 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / getPatternParamNames
+
+# Function: getPatternParamNames()
+
+```ts
+function getPatternParamNames(pattern): string[];
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L26)
+
+Reads the names of every `:param` of a route pattern of the route map.
+
+The names come from the parse of `pattern-grammar.ts`, which reads the WHOLE grammar:
+a `{…}` group and a `(\d+)` constraint both hide a name from an expression that looks
+for `:name` alone. An ANONYMOUS param — `*` and a bare `(\d+)` — carries no name, and
+the list therefore holds none.
+
+## 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
+`parsePattern` caches the parse that it reads.

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

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / getRequiredPatternParamNames
+
+# Function: getRequiredPatternParamNames()
+
+```ts
+function getRequiredPatternParamNames(pattern): string[];
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L52)
+
+The names of every param the pattern REQUIRES, so an optional one is left out.
+
+A param is optional when its own modifier is `?` or `*`, and when EVERY group above it
+carries one of the two. `?` alone was the test before, and it read `/files/:path*` and
+`/books{/:id}?` as required patterns: a path that fills neither then counted as a gap,
+the pick was discarded, and a correct parse from Vue Router or SolidJS Router went with
+it. That is the same class of defect as the all-optional bug of !133, for the modifiers
+that the fix did not cover.
+
+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 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.
+
+## 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 `parsePattern` caches the parse that it reads.

package/api/@xmachines/play-router/{functions → index/functions}/isMountableBridge.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / isMountableBridge
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / isMountableBridge
 
 # Function: isMountableBridge()
 
@@ -6,7 +6,7 @@
 function isMountableBridge(bridge): bridge is MountableRouterBridge;
 ```
 
-Defined in: [provider-lifecycle.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L116)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L125)
 
 Tells you whether a bridge can move its mount.
 

package/api/@xmachines/play-router/index/functions/joinBasePath.md

@@ -0,0 +1,37 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / joinBasePath
+
+# Function: joinBasePath()
+
+```ts
+function joinBasePath(basePath, path): string;
+```
+
+Defined in: [packages/play-url/src/base-path.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L302)
+
+Adds the base path to an outbound path of the machine.
+
+The function joins the PATHNAME only. A query string and a hash fragment of the
+path of the machine stay at the end, because the prefix belongs in front of the
+path.
+
+## Parameters
+
+| Parameter  | Type     | Description                                                                      |
+| ---------- | -------- | -------------------------------------------------------------------------------- |
+| `basePath` | `string` | The concrete prefix of [resolveBasePath](resolveBasePath.md). `""` adds nothing. |
+| `path`     | `string` | The path of the machine, for example `"/dashboard"` or `"/dates?trip=one-way"`.  |
+
+## Returns
+
+`string`
+
+The location for the router of the host.
+
+## Example
+
+```typescript
+joinBasePath("/abc123/play", "/dashboard"); // "/abc123/play/dashboard"
+joinBasePath("/abc123/play", "/"); // "/abc123/play"
+joinBasePath("/abc123/play", "/x?tab=a"); // "/abc123/play/x?tab=a"
+joinBasePath("", "/dashboard"); // "/dashboard"
+```

package/api/@xmachines/play-router/{functions → index/functions}/mountKey.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / mountKey
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / mountKey
 
 # Function: mountKey()
 
@@ -6,7 +6,7 @@
 function mountKey(basePath?, basePathParams?): string;
 ```
 
-Defined in: [provider-lifecycle.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L134)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:143](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L143)
 
 A key that changes when the MOUNT changes, and never when its identity changes.
 

package/api/@xmachines/play-router/index/functions/normalizeBasePath.md

@@ -0,0 +1,43 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / normalizeBasePath
+
+# Function: normalizeBasePath()
+
+```ts
+function normalizeBasePath(basePath?): string;
+```
+
+Defined in: [packages/play-url/src/base-path.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L130)
+
+Normalizes a base path, and it substitutes no `:param` segment of that path.
+
+Use this function when you want the form of the pattern, for example to declare
+the routes of a machine in a route config of a host that substitutes each param
+itself. [resolveBasePath](resolveBasePath.md) gives the form that a bridge needs.
+
+## Parameters
+
+| Parameter   | Type     | Description                                                                                     |
+| ----------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `basePath?` | `string` | The prefix, as a pattern or as a concrete path. An absent value, `""`, and `"/"` all give `""`. |
+
+## Returns
+
+`string`
+
+The normalized prefix. It starts with `/`, and it carries no trailing `/`.
+
+## Throws
+
+For a wildcard segment, for an optional `:param?`
+segment, for a `$param` segment, for a query string or a hash fragment, for a URL
+scheme, for a dot segment (`.`, `..`, and their percent-encoded forms), and for any
+segment that a browser rewrites — one that holds whitespace, a backslash, or a
+character that a URL percent-encodes.
+
+## Example
+
+```typescript
+normalizeBasePath("/:machineId/play/"); // "/:machineId/play"
+normalizeBasePath("admin"); // "/admin"
+normalizeBasePath("/"); // ""
+```

package/api/@xmachines/play-router/{functions → index/functions}/openProviderBridge.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / openProviderBridge
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / openProviderBridge
 
 # Function: openProviderBridge()
 
@@ -6,7 +6,7 @@
 function openProviderBridge<TRouter, TActor>(BridgeCtor, __namedParameters): object;
 ```
 
-Defined in: [provider-lifecycle.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L177)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L189)
 
 Builds a bridge, connects it, and hands back the way to close it.
 
@@ -17,17 +17,17 @@ disconnect a later one when two mounts overlap.
 
 ## Type Parameters
 
-| Type Parameter                                               |
-| ------------------------------------------------------------ |
-| `TRouter`                                                    |
-| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) |
+| Type Parameter                                                       |
+| -------------------------------------------------------------------- |
+| `TRouter`                                                            |
+| `TActor` _extends_ [`RoutableActor`](../interfaces/RoutableActor.md) |
 
 ## Parameters
 
-| Parameter           | Type                                                                                         |
-| ------------------- | -------------------------------------------------------------------------------------------- |
-| `BridgeCtor`        | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> |
-| `__namedParameters` | [`OpenProviderBridgeArgs`](../interfaces/OpenProviderBridgeArgs.md)\<`TRouter`, `TActor`\>   |
+| Parameter           | Type                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------ |
+| `BridgeCtor`        | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`, `TActor`\> |
+| `__namedParameters` | [`OpenProviderBridgeArgs`](../interfaces/OpenProviderBridgeArgs.md)\<`TRouter`, `TActor`\>             |
 
 ## Returns
 
@@ -35,7 +35,7 @@ disconnect a later one when two mounts overlap.
 
 The bridge, and a `close` that disconnects it one time.
 
-| Name      | Type                                            | Defined in                                                                                                                                |
-| --------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `bridge`  | [`RouterBridge`](../interfaces/RouterBridge.md) | [provider-lifecycle.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L180) |
-| `close()` | () => `void`                                    | [provider-lifecycle.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L180) |
+| Name      | Type                                            | Defined in                                                                                                                                                         |
+| --------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bridge`  | [`RouterBridge`](../interfaces/RouterBridge.md) | [packages/play-router/src/provider-lifecycle.ts:192](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L192) |
+| `close()` | () => `void`                                    | [packages/play-router/src/provider-lifecycle.ts:192](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L192) |

package/api/@xmachines/play-router/index/functions/pickOwnParams.md

@@ -0,0 +1,41 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / pickOwnParams
+
+# Function: pickOwnParams()
+
+```ts
+function pickOwnParams(params, names, requiredNames?): Record<string, string> | null;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L84)
+
+Keeps the entries of `params` whose name the pattern of the machine declares, and
+only when the result covers EVERY name of that pattern.
+
+A complete pick is an answer, and a partial pick is not: a wrapper route of the host
+can declare a subset of the params of the machine — a tenant segment, for example,
+but not the document one — and keeping that subset drops the rest from a route that
+declares them. The caller falls back to its own extraction for `null`.
+
+The result has a null prototype, so a param named `__proto__` stays an own key.
+
+An OPTIONAL name of the pattern (`:name?`) is covered whether the framework reports
+it or not: a segment that did not match has no value, and that is a complete answer.
+At least one declared name must come back, though — a framework that reports none
+matched another route, and the path may still hold a value that only the fallback
+reads. A pattern whose params are ALL optional therefore always answers `null` here
+when the framework reports nothing; [resolveFrameworkParams](resolveFrameworkParams.md) then reads the PATH,
+which settles the question without the framework and without URLPattern.
+
+## Parameters
+
+| Parameter       | Type                           | Default value | Description                                                                                                                                                                                                                                                                    |
+| --------------- | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `params`        | `Record`\<`string`, `string`\> | `undefined`   | The params of the framework router. [cleanFrameworkParams](cleanFrameworkParams.md) removes each empty value already, and one that reaches here anyway counts as absent: an empty value says that the segment did not match, and never that the path carries the empty string. |
+| `names`         | readonly `string`[]            | `undefined`   | The names that the pattern of the machine declares.                                                                                                                                                                                                                            |
+| `requiredNames` | readonly `string`[]            | `names`       | The names the pattern REQUIRES. The default treats every name as required, so a two-argument call keeps the strict test.                                                                                                                                                       |
+
+## Returns
+
+`Record`\<`string`, `string`\> \| `null`
+
+The params of the machine, or `null` when the framework covers them not.

package/api/@xmachines/play-router/{functions → index/functions}/repointProviderBridge.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / repointProviderBridge
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / repointProviderBridge
 
 # Function: repointProviderBridge()
 
@@ -6,7 +6,7 @@
 function repointProviderBridge(bridge, basePath?, basePathParams?): void;
 ```
 
-Defined in: [provider-lifecycle.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L241)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:253](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L253)
 
 Moves the mount of a live bridge, and rebuilds nothing.
 

package/api/@xmachines/play-router/index/functions/resolveBasePath.md

@@ -0,0 +1,51 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / resolveBasePath
+
+# Function: resolveBasePath()
+
+```ts
+function resolveBasePath(basePath?, params?): ResolvedBasePath;
+```
+
+Defined in: [packages/play-url/src/base-path.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L180)
+
+Resolves a base path and its params to the concrete prefix that a browser URL
+carries.
+
+A bridge calls this function one time, and again on each `setBasePath()` call. The
+result is always concrete. [stripBasePath](stripBasePath.md) therefore compares a literal
+prefix, and no URLPattern match runs on the hot path of a navigation.
+
+## Parameters
+
+| Parameter   | Type                                       | Description                                        |
+| ----------- | ------------------------------------------ | -------------------------------------------------- |
+| `basePath?` | `string`                                   | The prefix, as a pattern or as a concrete path.    |
+| `params?`   | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of `basePath`. |
+
+## Returns
+
+[`ResolvedBasePath`](../interfaces/ResolvedBasePath.md)
+
+The concrete prefix, and the values of each param for a `play.route` event.
+
+## Throws
+
+For a wildcard segment, for an optional `:param?`
+segment, for a `$param` segment, for a query string or a hash fragment, for a URL
+scheme, for a dot segment (`.`, `..`, and their percent-encoded forms), and for any
+segment that a browser rewrites — one that holds whitespace, a backslash, or a
+character that a URL percent-encodes.
+
+## Throws
+
+When a `:param` of the prefix has no value.
+
+## Example
+
+```typescript
+resolveBasePath("/:machineId/play", { machineId: "abc123" });
+// → { path: "/abc123/play", params: { machineId: "abc123" } }
+
+resolveBasePath("/admin");
+// → { path: "/admin", params: {} }
+```

package/api/@xmachines/play-router/{functions → index/functions}/resolveFrameworkParams.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / resolveFrameworkParams
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / resolveFrameworkParams
 
 # Function: resolveFrameworkParams()
 
@@ -6,18 +6,17 @@
 function resolveFrameworkParams(__namedParameters): Record<string, string>;
 ```
 
-Defined in: [framework-params.ts:298](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L298)
+Defined in: [packages/play-url/src/framework-params.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L261)
 
 Decides which params describe the route of the machine.
 
-The three branches, in the order that they apply:
+The four branches, in the order that they apply:
 
 - **The pattern declares no name** — a static path, a bare `*` wildcard, or an
   unknown stateId. The answer is `{}`. The params of the framework must NOT travel
   here: under a catch-all they hold the splat of the host, and that value would reach
-  the actor as a param of the machine. This branch also reaches no URLPattern, which
-  matters: the extraction needs the constructor even for a pattern with no parameter,
-  so a delegation would throw on a runtime without the API.
+  the actor as a param of the machine. A bare `*` names nothing that a machine can
+  read, and URLPattern numbers its group `0`.
 - **The bridge sits under a mount** — the framework matched a route of the HOST by
   construction, because the machine owns the suffix of the path only. Its params
   therefore describe this pattern never, whatever they are named, and a name that
@@ -27,16 +26,15 @@ The three branches, in the order that they apply:
   its parse, together with its decoding. An optional `:name?` that the framework
   reports not is covered too: a segment that did not match has no value. A gap in a
   required name falls back, because keeping it would drop a name the route declares.
-- **The path IS the bare form of the pattern** — every optional segment is absent, so
-  `{}` is the complete answer. The branch reads the path and trusts the framework with
+- **The path IS the bare form of the pattern** — every optional part is absent, so `{}`
+  is the complete answer. The branch reads the path and trusts the framework with
   nothing, which is what makes it safe under a catch-all of the host, and it calls
   URLPattern for a location that needs none.
 
-None of this decides whether the APPLICATION needs a URLPattern polyfill. A `RouteMap`
-that holds one parameterized route compiles it in the CONSTRUCTOR, and it throws a
-`URLPatternUnavailableError` there when the runtime has no URLPattern. The polyfill
-question is therefore settled at startup: only a route map of static paths alone
-escapes it. What these branches decide is whether a NAVIGATION calls URLPattern again.
+What these branches decide is whether a NAVIGATION compiles and runs a URLPattern
+again. The API itself is always present: `url-pattern-utils.ts` imports the polyfill as
+an ordinary dependency, and no code path asks whether the runtime carries the native
+one.
 
 ## Parameters