@xmachines/docs 3.0.0 → 4.0.0

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: [play-router/src/provider-lifecycle.ts:243](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L243)
+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: [play-router/src/framework-params.ts:298](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.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
 

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / sanitizePathname
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / sanitizePathname
 
 # Function: sanitizePathname()
 
@@ -6,7 +6,7 @@
 function sanitizePathname(pathname): string | null;
 ```
 
-Defined in: [play-router/src/router-sync.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L74)
+Defined in: [packages/play-router/src/router-sync.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L71)
 
 Normalizes a pathname before a lookup in the route map.
 

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

@@ -0,0 +1,44 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / stripBasePath
+
+# Function: stripBasePath()
+
+```ts
+function stripBasePath(pathname, basePath): string | null;
+```
+
+Defined in: [packages/play-url/src/base-path.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L276)
+
+Removes the base path from an inbound location of the router.
+
+The return value separates the two cases that make a shared router work:
+
+- A string is the MACHINE half of the location, for example `"/dashboard"` of
+  `"/abc123/play/dashboard"`. The bridge matches it against the route map.
+- `null` means that the location is FOREIGN: it lies outside the mount, so it
+  belongs to the host. The bridge sends no `play.route` event, AND it runs no
+  corrective navigation. A correction here would drag the user off a page of the
+  host.
+
+The match is exact, and it respects each segment boundary. `"/abc/playground"` is
+therefore foreign to the mount `"/abc/play"`.
+
+## Parameters
+
+| Parameter  | Type     | Description                                                                         |
+| ---------- | -------- | ----------------------------------------------------------------------------------- |
+| `pathname` | `string` | A sanitized pathname of the router, with no query and no duplicate slash.           |
+| `basePath` | `string` | The concrete prefix of [resolveBasePath](resolveBasePath.md). `""` removes nothing. |
+
+## Returns
+
+`string` \| `null`
+
+The machine half of the path, or `null` when the location is foreign.
+
+## Example
+
+```typescript
+stripBasePath("/abc123/play/dashboard", "/abc123/play"); // "/dashboard"
+stripBasePath("/abc123/play", "/abc123/play"); // "/"
+stripBasePath("/settings", "/abc123/play"); // null — the host owns it
+```

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / validateRouteFormat
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / validateRouteFormat
 
 # Function: validateRouteFormat()
 
@@ -6,7 +6,7 @@
 function validateRouteFormat(routePath, stateId): void;
 ```
 
-Defined in: [play-router/src/validate-routes.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/validate-routes.ts#L27)
+Defined in: [packages/play-router/src/validate-routes.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/validate-routes.ts#L27)
 
 Checks the format of a route path
 

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / validateStateExists
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / validateStateExists
 
 # Function: validateStateExists()
 
@@ -6,7 +6,7 @@
 function validateStateExists(stateId, stateIds): void;
 ```
 
-Defined in: [play-router/src/validate-routes.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/validate-routes.ts#L43)
+Defined in: [packages/play-router/src/validate-routes.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/validate-routes.ts#L43)
 
 Checks that the set of the state IDs holds a state
 

package/api/@xmachines/play-router/{interfaces → index/interfaces}/BasePathOptions.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / BasePathOptions
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / BasePathOptions
 
 # Interface: BasePathOptions
 
-Defined in: [play-router/src/base-path.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L44)
+Defined in: [packages/play-url/src/base-path.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L44)
 
 The base-path options that every router bridge, `connectRouter` function, and
 `PlayRouterProvider` component accepts.
@@ -26,7 +26,7 @@ connectRouter({
 
 ## Properties
 
-| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                            |
-| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [play-router/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L58) |
-| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they 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. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-router/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L72) |
+| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                               |
+| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [packages/play-url/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L58) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they 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. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [packages/play-url/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L72) |

package/api/@xmachines/play-router/index/interfaces/BuildPlayRouteEventOptions.md

@@ -0,0 +1,13 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / BuildPlayRouteEventOptions
+
+# Interface: BuildPlayRouteEventOptions
+
+Defined in: [packages/play-router/src/router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L14)
+
+## Properties
+
+| Property                                  | Type                                                   | Defined in                                                                                                                                         |
+| ----------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match`       | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [packages/play-router/src/router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L17) |
+| <a id="property-pathname"></a> `pathname` | `string`                                               | [packages/play-router/src/router-sync.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L15) |
+| <a id="property-search"></a> `search?`    | `string`                                               | [packages/play-router/src/router-sync.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-sync.ts#L16) |

package/api/@xmachines/play-router/index/interfaces/FrameworkParamsSource.md

@@ -0,0 +1,47 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / FrameworkParamsSource
+
+# Interface: FrameworkParamsSource
+
+Defined in: [packages/play-url/src/framework-params.ts:212](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L212)
+
+What [resolveFrameworkParams](../functions/resolveFrameworkParams.md) needs from the bridge that calls it.
+
+## Properties
+
+| Property                                   | Type                              | Description                                                                                                                                                                                                                             | Defined in                                                                                                                                               |
+| ------------------------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath`  | `string`                          | The resolved prefix of the mount. `""` means that the machine owns the router.                                                                                                                                                          | [packages/play-url/src/framework-params.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L216) |
+| <a id="property-pathname"></a> `pathname?` | `string`                          | The machine-side path of the location, with the mount prefix already removed. The field is OPTIONAL, so a caller that was written before it keeps its behaviour: the one branch that reads it falls back without it, exactly as it did. | [packages/play-url/src/framework-params.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L223) |
+| <a id="property-pattern"></a> `pattern`    | `string` \| `null` \| `undefined` | The route pattern of the match, from `routeMap.getPathByStateId`.                                                                                                                                                                       | [packages/play-url/src/framework-params.ts:214](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L214) |
+
+## Methods
+
+### fallback()
+
+```ts
+fallback(): Record<string, string>;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L227)
+
+The URLPattern extraction of the base class, read lazily.
+
+#### Returns
+
+`Record`\<`string`, `string`\>
+
+---
+
+### frameworkParams()
+
+```ts
+frameworkParams(): Record<string, string>;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L225)
+
+The params of the framework router, read lazily and cleaned of empty values.
+
+#### Returns
+
+`Record`\<`string`, `string`\>

package/api/@xmachines/play-router/{interfaces → index/interfaces}/LocationLike.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / LocationLike
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / LocationLike
 
 # Interface: LocationLike
 
-Defined in: [play-router/src/types.ts:480](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L480)
+Defined in: [packages/play-router/src/types.ts:559](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L559)
 
 The minimal location interface of an adapter that reads the current URL at the
 moment of `connect()`. You can inject it for SSR and for a test: give a mock in
@@ -21,7 +21,7 @@ connectRouter({ actor, routeMap, location: mockLoc });
 
 ## Properties
 
-| Property                                  | Modifier   | Type     | Defined in                                                                                                                      |
-| ----------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [play-router/src/types.ts:481](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L481) |
-| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:482](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L482) |
+| Property                                  | Modifier   | Type     | Defined in                                                                                                                               |
+| ----------------------------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [packages/play-router/src/types.ts:560](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L560) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [packages/play-router/src/types.ts:561](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L561) |

package/api/@xmachines/play-router/{interfaces → index/interfaces}/MountableRouterBridge.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / MountableRouterBridge
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / MountableRouterBridge
 
 # Interface: MountableRouterBridge
 
-Defined in: [play-router/src/types.ts:416](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L416)
+Defined in: [packages/play-router/src/types.ts:495](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L495)
 
 A `RouterBridge` whose machine is mounted at a URL prefix that can MOVE while the
 bridge stays connected.
@@ -31,10 +31,10 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 ## Properties
 
-| Property                                              | Modifier   | Type                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                      |
-| ----------------------------------------------------- | ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath`             | `readonly` | `string`                                     | The resolved URL prefix of the mount, or `""` when the machine owns the complete router.                                                                                                                                                                                                                                                                                                                                  | [play-router/src/types.ts:418](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L418) |
-| <a id="property-basepathparams"></a> `basePathParams` | `readonly` | `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. | [play-router/src/types.ts:428](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L428) |
+| Property                                              | Modifier   | Type                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                               |
+| ----------------------------------------------------- | ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath`             | `readonly` | `string`                                     | The resolved URL prefix of the mount, or `""` when the machine owns the complete router.                                                                                                                                                                                                                                                                                                                                  | [packages/play-router/src/types.ts:497](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L497) |
+| <a id="property-basepathparams"></a> `basePathParams` | `readonly` | `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. | [packages/play-router/src/types.ts:507](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L507) |
 
 ## Methods
 
@@ -44,7 +44,7 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L376)
+Defined in: [packages/play-router/src/types.ts:455](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L455)
 
 Connects the router bridge to the Actor
 
@@ -78,7 +78,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L392)
+Defined in: [packages/play-router/src/types.ts:471](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L471)
 
 Disconnects the router bridge from the Actor
 
@@ -110,7 +110,7 @@ await bridge.disconnect();
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/types.ts:436](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L436)
+Defined in: [packages/play-router/src/types.ts:515](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L515)
 
 Moves the machine to a different mount point.
 

package/api/@xmachines/play-router/{interfaces → index/interfaces}/OpenProviderBridgeArgs.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / OpenProviderBridgeArgs
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / OpenProviderBridgeArgs
 
 # Interface: OpenProviderBridgeArgs\<TRouter, TActor\>
 
-Defined in: [play-router/src/provider-lifecycle.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L163)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:170](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L170)
 
 What [openProviderBridge](../functions/openProviderBridge.md) needs to build and connect a bridge.
 
@@ -12,17 +12,17 @@ What [openProviderBridge](../functions/openProviderBridge.md) needs to build and
 
 ## Type Parameters
 
-| Type Parameter                                 |
-| ---------------------------------------------- |
-| `TRouter`                                      |
-| `TActor` _extends_ [`PlayActor`](PlayActor.md) |
+| Type Parameter                                         |
+| ------------------------------------------------------ |
+| `TRouter`                                              |
+| `TActor` _extends_ [`RoutableActor`](RoutableActor.md) |
 
 ## Properties
 
-| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Inherited from                                                                                         | Defined in                                                                                                                                                |
-| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                    | `public`   | `TActor`                                   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                      | [play-router/src/provider-lifecycle.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L165) |
-| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](BasePathOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [`BasePathOptions`](BasePathOptions.md).[`basePath`](BasePathOptions.md#property-basepath)             | [play-router/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L58)                     |
-| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](BasePathOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they 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. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [`BasePathOptions`](BasePathOptions.md).[`basePathParams`](BasePathOptions.md#property-basepathparams) | [play-router/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L72)                     |
-| <a id="property-routemap"></a> `routeMap`              | `public`   | [`RouteMap`](../classes/RouteMap.md)       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                      | [play-router/src/provider-lifecycle.ts:166](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L166) |
-| <a id="property-router"></a> `router`                  | `public`   | `TRouter`                                  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                      | [play-router/src/provider-lifecycle.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L164) |
+| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Inherited from                                                                                         | Defined in                                                                                                                                                         |
+| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-actor"></a> `actor`                    | `public`   | `TActor`                                   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                      | [packages/play-router/src/provider-lifecycle.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L175) |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](BasePathOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [`BasePathOptions`](BasePathOptions.md).[`basePath`](BasePathOptions.md#property-basepath)             | [packages/play-url/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L58)                           |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](BasePathOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they 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. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [`BasePathOptions`](BasePathOptions.md).[`basePathParams`](BasePathOptions.md#property-basepathparams) | [packages/play-url/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L72)                           |
+| <a id="property-routemap"></a> `routeMap`              | `public`   | [`RouteMap`](../classes/RouteMap.md)       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                      | [packages/play-router/src/provider-lifecycle.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L176) |
+| <a id="property-router"></a> `router`                  | `public`   | `TRouter`                                  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | -                                                                                                      | [packages/play-router/src/provider-lifecycle.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L174) |