@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/play-router/{classes → index/classes}/RouteMap.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMap
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / RouteMap
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L105)
+Defined in: [packages/play-router/src/base-route-map.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L111)
 
 The shared base class of the route map for both directions.
 
@@ -17,12 +17,18 @@ of its own, and it inherits the complete public API from here.
 - The class keeps each result of a first match in an LRU cache. The default size
   is 500 entries, and the `cacheSize` constructor option changes it
 
-**The syntax of a pattern** (`:param`, `:param?`, and `*`):
+**The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+often are:
 
 - `:param` — a necessary segment. It matches exactly one segment without a `/`
 - `:param?` — an optional segment. It matches zero segments or one segment without a `/`
 - `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
+A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+too. The [routing guide](../../../../../guides/routing.md) states every form, the prefix
+rule, and the one divergence from the standard: a param name of this library can hold a
+hyphen.
+
 **The forms of a stateId:** you can register a stateId, and you can look one up,
 in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
 canonical form itself. `getStateIdByPath` returns the stateId exactly as you
@@ -58,7 +64,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L133)
+Defined in: [packages/play-router/src/base-route-map.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L139)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -87,7 +93,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L229)
+Defined in: [packages/play-router/src/base-route-map.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L242)
 
 Returns the path pattern of a state ID.
 
@@ -123,7 +129,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
+Defined in: [packages/play-router/src/base-route-map.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L197)
 
 Resolves a URL path to its state ID.
 

package/api/@xmachines/play-router/{classes → index/classes}/RouterBridgeBase.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouterBridgeBase
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / RouterBridgeBase
 
 # Abstract Class: RouterBridgeBase
 
-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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L113)
 
 A `RouterBridge` whose machine is mounted at a URL prefix that can MOVE while the
 bridge stays connected.
@@ -27,14 +27,15 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 ## Extended by
 
-- [`DomRouterBridge`](../../play-dom-router/classes/DomRouterBridge.md)
-- [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
-- [`TanStackRouterBridgeBase`](../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
-- [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
-- [`SvelteKitRouterBridge`](../../play-sveltekit-router/classes/SvelteKitRouterBridge.md)
-- [`SvelteSpaRouterBridge`](../../play-svelte-spa-router/classes/SvelteSpaRouterBridge.md)
-- [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
-- [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
+- [`DomRouterBridge`](../../../play-dom-router/classes/DomRouterBridge.md)
+- [`ReactRouterBridge`](../../../play-react-router/classes/ReactRouterBridge.md)
+- [`TanStackRouterBridgeBase`](../../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
+- [`SolidRouterBridge`](../../../play-solid-router/classes/SolidRouterBridge.md)
+- [`SvelteKitRouterBridge`](../../../play-sveltekit-router/classes/SvelteKitRouterBridge.md)
+- [`SvelteSpaRouterBridge`](../../../play-svelte-spa-router/classes/SvelteSpaRouterBridge.md)
+- [`TanStackReactRouterBridge`](../../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
+- [`TanStackSolidRouterBridge`](../../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
+- [`VueRouterBridge`](../../../play-vue-router/index/classes/VueRouterBridge.md)
 
 ## Implements
 
@@ -48,10 +49,11 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 new RouterBridgeBase(
    actor,
    routeMap,
-   options?): RouterBridgeBase;
+   options?
+): RouterBridgeBase;
 ```
 
-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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L231)
 
 #### Parameters
 
@@ -77,7 +79,7 @@ Defined in: [play-router/src/router-bridge-base.ts:230](https://gitlab.com/xmach
 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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L256)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -102,7 +104,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:285](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L285)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -153,7 +155,7 @@ mount while the machine stays on the same route, and no event goes out.
 connect(): void;
 ```
 
-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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:507](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L507)
 
 Connects the router bridge to the Actor.
 
@@ -187,7 +189,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:765](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L765)
 
 Disconnects the router bridge from the Actor.
 
@@ -210,7 +212,7 @@ framework.
 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)
+Defined in: [packages/play-router/src/router-bridge-base.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L325)
 
 Moves the machine to a different mount point, while it stays connected.
 

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / buildPlayRouteEvent
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / buildPlayRouteEvent
 
 # Function: buildPlayRouteEvent()
 
@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-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)
+Defined in: [packages/play-router/src/router-sync.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L189)
 
 Builds a normalized `play.route` event from the raw input of a router or of a
 browser.

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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [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)
+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: [play-router/src/provider-lifecycle.ts:136](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L136)
+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: [play-router/src/provider-lifecycle.ts:179](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L179)
+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) | [play-router/src/provider-lifecycle.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L182) |
-| `close()` | () => `void`                                    | [play-router/src/provider-lifecycle.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L182) |
+| 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) |