@xmachines/docs 3.0.0 → 5.0.0

package/api/@xmachines/play-url/index/functions/getCompiledPattern.md

@@ -0,0 +1,32 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getCompiledPattern
+
+# Function: getCompiledPattern()
+
+```ts
+function getCompiledPattern(pattern, options?): URLPatternLike;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/url-pattern-utils.ts#L187)
+
+Compiles a route pattern into a `URLPattern`, and it uses the cache of the module level
+again.
+
+[ParsedPattern.normalized](../interfaces/ParsedPattern.md#property-normalized) carries the pattern that the compilation reads. A param name
+with a hyphen (`:cat-id`) therefore becomes a valid URLPattern identifier (`:cat_id`).
+A caller that reads the values of the groups must map each normalized name back with
+[ParsedPattern.declaredNames](../interfaces/ParsedPattern.md#property-declarednames).
+
+## Parameters
+
+| Parameter | Type                                                | Description                                                                                                                                                                              |
+| --------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pattern` | `string`                                            | The string of the route pattern, for example `/profile/:userId`                                                                                                                          |
+| `options` | [`CompileOptions`](../interfaces/CompileOptions.md) | See [CompileOptions](../interfaces/CompileOptions.md). This function reads TWO caches, so neither option is named `cache`: one holds the PARSE and the other holds the COMPILED pattern. |
+
+## Returns
+
+[`URLPatternLike`](../type-aliases/URLPatternLike.md)
+
+## Throws
+
+When URLPattern cannot compile the pattern.

package/api/@xmachines/play-url/index/functions/getIndexKey.md

@@ -0,0 +1,30 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getIndexKey
+
+# Function: getIndexKey()
+
+```ts
+function getIndexKey(path): string;
+```
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:201](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L201)
+
+Computes the key of the bucket index of a concrete PATH.
+
+The key is the first path segment, for example `"settings"` of `"/settings/billing"`.
+The root path `"/"` gives the key `"/"`, and a path whose first segment is EMPTY —
+`"//docs"` — gives the key `""`. The two are different keys, so a pattern that matches
+both asks [ParsedPattern.indexKey](../interfaces/ParsedPattern.md#property-indexkey) for the wildcard key instead.
+
+[ParsedPattern.indexKey](../interfaces/ParsedPattern.md#property-indexkey) computes the key of a PATTERN, and it calls this
+function for every pattern whose first segment is a literal. One function therefore
+answers both sides, and a pattern in the wrong bucket cannot happen.
+
+## Parameters
+
+| Parameter | Type     | Description               |
+| --------- | -------- | ------------------------- |
+| `path`    | `string` | The string of a URL path. |
+
+## Returns
+
+`string`

package/api/@xmachines/play-url/index/functions/holdsUnsubstitutedParam.md

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / holdsUnsubstitutedParam
+
+# Function: holdsUnsubstitutedParam()
+
+```ts
+function holdsUnsubstitutedParam(pathname): boolean;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/url-pattern-utils.ts#L96)
+
+Tells you if a CONCRETE path still carries a param that nothing substituted.
+
+This is a different question from the `parameterized` field of a parse, and it needs a
+different test. `RouterBridgeBase.resolveNavigationPath` asks it about a value that the
+ACTOR reports, which is a real path built from real param values — and a real path
+carries a character of the pattern grammar whenever a param value does. `/search/a+b`,
+`/tags/c++`, `/docs/rfc(2119)` and `/i18n/{en}` are all ordinary locations, and the
+grammar reads a modifier, a constraint and a group in them. A bridge that judged them
+by the grammar refused to navigate, and it said nothing.
+
+The test is therefore narrow on purpose: `:` and `*` are the two characters that mark a
+param a substitution did not fill, and a path that holds one of them can reach the URL
+bar never. A param VALUE that holds one of them is refused too, which is the price, and
+it is the price this library paid before the grammar existed.
+
+## Parameters
+
+| Parameter  | Type     | Description                                                          |
+| ---------- | -------- | -------------------------------------------------------------------- |
+| `pathname` | `string` | The PATHNAME half of an actor route, with the query already removed. |
+
+## Returns
+
+`boolean`
+
+`true` when the path cannot go to the URL bar as it stands

package/api/@xmachines/play-url/index/functions/isDotSegment.md

@@ -0,0 +1,40 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / isDotSegment
+
+# Function: isDotSegment()
+
+```ts
+function isDotSegment(segment): boolean;
+```
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:872](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L872)
+
+Answers whether one segment resolves away in a URL, rather than naming itself.
+
+A URL parser reads the dot segments BEFORE it decodes the percent escapes, and it counts
+`%2e` as the dot. The WHATWG URL standard names six forms, and a browser resolves every
+one of them out of a location: `.` and `%2e` for the single dot, and `..`, `.%2e`, `%2e.`
+and `%2e%2e` for the double dot. Each percent test is case-insensitive.
+
+NO encoding of `.` or `..` therefore survives. A param that carries one describes a path
+that its own pattern matches back never, so [buildPath](buildPath.md) refuses it, and
+`normalizeBasePath` of `@xmachines/play-url` refuses the same value in a base path.
+
+Give the segment in the form that the URL carries, and encode nothing here. The two
+callers reach that form by two roads, and both are correct. [buildPath](buildPath.md) encodes a
+param value first, so a value that HOLDS a percent sign arrives with that sign escaped:
+the string `"%2e"` encodes to `"%252e"`, which names itself and stays. `normalizeBasePath`
+of `@xmachines/play-url` reads a path that an author wrote, which is encoded already, so
+it passes the segment RAW and `"%2e"` there is the dot. A caller that encodes an
+already-encoded segment a second time hides every `%2e` from this test.
+
+## Parameters
+
+| Parameter | Type     | Description                                                                         |
+| --------- | -------- | ----------------------------------------------------------------------------------- |
+| `segment` | `string` | ONE path segment, with no separator around it, in the form that the URL carries it. |
+
+## Returns
+
+`boolean`
+
+`true` when a URL resolves the segment away.

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / joinBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / joinBasePath
 
 # Function: joinBasePath()
 
@@ -6,7 +6,7 @@
 function joinBasePath(basePath, path): string;
 ```
 
-Defined in: [play-router/src/base-path.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L302)
+Defined in: [packages/play-url/src/base-path.ts:307](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L307)
 
 Adds the base path to an outbound path of the machine.
 
@@ -33,5 +33,6 @@ The location for the router of the host.
 joinBasePath("/abc123/play", "/dashboard"); // "/abc123/play/dashboard"
 joinBasePath("/abc123/play", "/"); // "/abc123/play"
 joinBasePath("/abc123/play", "/x?tab=a"); // "/abc123/play/x?tab=a"
+joinBasePath("/abc123/play", "#/home"); // "/abc123/play#/home"
 joinBasePath("", "/dashboard"); // "/dashboard"
 ```

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / normalizeBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / normalizeBasePath
 
 # Function: normalizeBasePath()
 
@@ -6,7 +6,7 @@
 function normalizeBasePath(basePath?): string;
 ```
 
-Defined in: [play-router/src/base-path.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L130)
+Defined in: [packages/play-url/src/base-path.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L134)
 
 Normalizes a base path, and it substitutes no `:param` segment of that path.
 

package/api/@xmachines/play-url/index/functions/parsePattern.md

@@ -0,0 +1,28 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / parsePattern
+
+# Function: parsePattern()
+
+```ts
+function parsePattern(pattern, options?): ParsedPattern;
+```
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L264)
+
+Reads a route pattern, one time for each distinct pattern.
+
+The parser reports a fault never. A pattern that it cannot read reports
+`parameterized: true` and `bareForm: null`, which sends it to the URLPattern
+constructor and keeps every derived answer on the safe side.
+
+## Parameters
+
+| Parameter  | Type                                            | Description                                        |
+| ---------- | ----------------------------------------------- | -------------------------------------------------- |
+| `pattern`  | `string`                                        | The route pattern, for example `/profile/:userId`. |
+| `options?` | [`ParseOptions`](../interfaces/ParseOptions.md) | -                                                  |
+
+## Returns
+
+[`ParsedPattern`](../interfaces/ParsedPattern.md)
+
+The parse. The caller treats it as read-only: the cache holds this object.

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / pickOwnParams
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / pickOwnParams
 
 # Function: pickOwnParams()
 
@@ -6,7 +6,7 @@
 function pickOwnParams(params, names, requiredNames?): Record<string, string> | null;
 ```
 
-Defined in: [play-router/src/framework-params.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/framework-params.ts#L117)
+Defined in: [packages/play-url/src/framework-params.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L43)
 
 Keeps the entries of `params` whose name the pattern of the machine declares, and
 only when the result covers EVERY name of that pattern.
@@ -31,8 +31,8 @@ which settles the question without the framework and without URLPattern.
 | 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`         | `string`[]                     | `undefined`   | The names that the pattern of the machine declares.                                                                                                                                                                                                                            |
-| `requiredNames` | `string`[]                     | `names`       | The names the pattern REQUIRES. The default treats every name as required, so a two-argument call keeps the strict test.                                                                                                                                                       |
+| `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
 

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / resolveBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / resolveBasePath
 
 # Function: resolveBasePath()
 
@@ -6,7 +6,7 @@
 function resolveBasePath(basePath?, params?): ResolvedBasePath;
 ```
 
-Defined in: [play-router/src/base-path.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L180)
+Defined in: [packages/play-url/src/base-path.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L184)
 
 Resolves a base path and its params to the concrete prefix that a browser URL
 carries.

package/api/@xmachines/play-url/index/functions/resolveFrameworkParams.md

@@ -0,0 +1,49 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / resolveFrameworkParams
+
+# Function: resolveFrameworkParams()
+
+```ts
+function resolveFrameworkParams(source): Record<string, string>;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L220)
+
+Decides which params describe the route of the machine.
+
+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. 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
+  happens to collide carries the value of the host. Read the params of the machine
+  from its own pattern instead.
+- **The framework covers every REQUIRED name** — it matched the machine route. Keep
+  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 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.
+
+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
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `source`  | [`FrameworkParamsSource`](../interfaces/FrameworkParamsSource.md) |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+The path parameters of the machine route, or `{}`.

package/api/@xmachines/play-url/index/functions/sanitizePathname.md

@@ -0,0 +1,27 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / sanitizePathname
+
+# Function: sanitizePathname()
+
+```ts
+function sanitizePathname(pathname): string | null;
+```
+
+Defined in: [packages/play-url/src/location.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/location.ts#L89)
+
+Reads the pathname of a location, and refuses a location that no route can match.
+
+The function removes the query and the fragment, and it joins every run of separators
+into one: `//docs//api` gives `/docs/api`. A route map holds one pattern for one path,
+and a doubled separator is the same path written another way.
+
+## Parameters
+
+| Parameter  | Type     | Description                                    |
+| ---------- | -------- | ---------------------------------------------- |
+| `pathname` | `string` | The raw value that a framework router reports. |
+
+## Returns
+
+`string` \| `null`
+
+The clean pathname, or `null` when the value is longer than 2048 characters.

package/api/@xmachines/play-url/index/functions/splitLocation.md

@@ -0,0 +1,37 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / splitLocation
+
+# Function: splitLocation()
+
+```ts
+function splitLocation(location): SplitLocation;
+```
+
+Defined in: [packages/play-url/src/location.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/location.ts#L55)
+
+Splits a location into its pathname, its query and its fragment.
+
+The search for the `#` starts at the SECOND character, so a leading `#` belongs to the
+pathname. A hash router writes a location of the form `#/home`, and that location names
+the path `#/home` and no fragment. The rule decides `#` alone, and a `?` ends the
+pathname wherever it stands.
+
+## Parameters
+
+| Parameter  | Type     | Description                                             |
+| ---------- | -------- | ------------------------------------------------------- |
+| `location` | `string` | The location string, for example `/docs?tab=api#intro`. |
+
+## Returns
+
+[`SplitLocation`](../interfaces/SplitLocation.md)
+
+The parts. Each absent part is `""`, and never `undefined`.
+
+## Example
+
+```typescript
+splitLocation("/docs?tab=api#intro");
+// → { pathname: "/docs", query: "tab=api", fragment: "#intro", suffix: "?tab=api#intro" }
+
+splitLocation("#/home"); // → { pathname: "#/home", query: "", fragment: "", suffix: "" }
+```

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

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / stripBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / stripBasePath
 
 # Function: stripBasePath()
 
@@ -6,7 +6,7 @@
 function stripBasePath(pathname, basePath): string | null;
 ```
 
-Defined in: [play-router/src/base-path.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L276)
+Defined in: [packages/play-url/src/base-path.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L280)
 
 Removes the base path from an inbound location of the router.
 

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

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / BasePathOptions
+[API](../../../../README.md) / [@xmachines/play-url](../../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:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L48)
 
 The base-path options that every router bridge, `connectRouter` function, and
 `PlayRouterProvider` component accepts.
@@ -20,13 +20,9 @@ connectRouter({
 });
 ```
 
-## Extended by
-
-- [`OpenProviderBridgeArgs`](OpenProviderBridgeArgs.md)
-
 ## 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:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L62) |
+| <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:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L76) |

package/api/@xmachines/play-url/index/interfaces/CompileOptions.md

@@ -0,0 +1,21 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / CompileOptions
+
+# Interface: CompileOptions
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:106](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/url-pattern-utils.ts#L106)
+
+What [getCompiledPattern](../functions/getCompiledPattern.md) reads: [ParseOptions](ParseOptions.md) with the compiled cache.
+
+A caller holds ONE object and hands it to every call of the routing layer, because
+`RouteMapOptions` and `RouterBridgeOptions` extend this one in turn.
+
+## Extends
+
+- [`ParseOptions`](ParseOptions.md)
+
+## Properties
+
+| Property                                             | Modifier   | Type                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Inherited from                                                                            | Defined in                                                                                                                                                 |
+| ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-compiledcache"></a> `compiledCache?` | `readonly` | [`PatternCache`](PatternCache.md)\<[`URLPatternLike`](../type-aliases/URLPatternLike.md)\> | The cache of the COMPILED `URLPattern`, which is what this function returns. The default is a cache that this module shares with every caller of the process. Pass one to give a tenant or a request a compilation that no other evicts, and pass `{ get: () => undefined, set: () => {} }` to compile each time. A caller that passes `patternCache` for isolation passes this one too. The compiled cache is read FIRST, so a hit on it answers before the parse runs at all — a passed parse cache alone therefore isolates nothing once another caller has compiled the same pattern. | -                                                                                         | [packages/play-url/src/url-pattern-utils.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/url-pattern-utils.ts#L119) |
+| <a id="property-patterncache"></a> `patternCache?`   | `readonly` | [`PatternCache`](PatternCache.md)\<[`ParsedPattern`](ParsedPattern.md)\>                   | The cache of the PARSE of a pattern. The default is the cache that this package shares with every caller of the process.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`ParseOptions`](ParseOptions.md).[`patternCache`](ParseOptions.md#property-patterncache) | [packages/play-pattern/src/cache.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L40)                   |

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

@@ -0,0 +1,52 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / FrameworkParamsSource
+
+# Interface: FrameworkParamsSource
+
+Defined in: [packages/play-url/src/framework-params.ts:171](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L171)
+
+What [resolveFrameworkParams](../functions/resolveFrameworkParams.md) needs from the bridge that calls it.
+
+## Extends
+
+- [`ParseOptions`](ParseOptions.md)
+
+## Properties
+
+| Property                                           | Modifier   | Type                                                                     | Description                                                                                                                                                                                                                             | Inherited from                                                                            | Defined in                                                                                                                                               |
+| -------------------------------------------------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath`          | `public`   | `string`                                                                 | The resolved prefix of the mount. `""` means that the machine owns the router.                                                                                                                                                          | -                                                                                         | [packages/play-url/src/framework-params.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L175) |
+| <a id="property-pathname"></a> `pathname?`         | `public`   | `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:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L182) |
+| <a id="property-pattern"></a> `pattern`            | `public`   | `string` \| `null` \| `undefined`                                        | The route pattern of the match, from `routeMap.getPathByStateId`.                                                                                                                                                                       | -                                                                                         | [packages/play-url/src/framework-params.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L173) |
+| <a id="property-patterncache"></a> `patternCache?` | `readonly` | [`PatternCache`](PatternCache.md)\<[`ParsedPattern`](ParsedPattern.md)\> | The cache of the PARSE of a pattern. The default is the cache that this package shares with every caller of the process.                                                                                                                | [`ParseOptions`](ParseOptions.md).[`patternCache`](ParseOptions.md#property-patterncache) | [packages/play-pattern/src/cache.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L40)                 |
+
+## Methods
+
+### fallback()
+
+```ts
+fallback(): Record<string, string>;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:186](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L186)
+
+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:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L184)
+
+The params of the framework router, read lazily and cleaned of empty values.
+
+#### Returns
+
+`Record`\<`string`, `string`\>

package/api/@xmachines/play-url/index/interfaces/GroupPart.md

@@ -0,0 +1,15 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / GroupPart
+
+# Interface: GroupPart
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L92)
+
+A `{…}` group, which carries its own parts and its own modifier.
+
+## Properties
+
+| Property                                  | Modifier   | Type                                                       | Defined in                                                                                                                                                   |
+| ----------------------------------------- | ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-kind"></a> `kind`         | `readonly` | `"group"`                                                  | [packages/play-pattern/src/pattern-grammar.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L93) |
+| <a id="property-modifier"></a> `modifier` | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md)    | [packages/play-pattern/src/pattern-grammar.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L95) |
+| <a id="property-parts"></a> `parts`       | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | [packages/play-pattern/src/pattern-grammar.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L94) |

package/api/@xmachines/play-url/index/interfaces/LiteralPart.md

@@ -0,0 +1,14 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / LiteralPart
+
+# Interface: LiteralPart
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L59)
+
+A run of literal characters, with every escape already resolved.
+
+## Properties
+
+| Property                          | Modifier   | Type        | Description                                                     | Defined in                                                                                                                                                   |
+| --------------------------------- | ---------- | ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-kind"></a> `kind` | `readonly` | `"literal"` | -                                                               | [packages/play-pattern/src/pattern-grammar.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L60) |
+| <a id="property-text"></a> `text` | `readonly` | `string`    | The characters that a path must carry, for example `/settings`. | [packages/play-pattern/src/pattern-grammar.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L62) |

package/api/@xmachines/play-url/index/interfaces/ParamPart.md

@@ -0,0 +1,21 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ParamPart
+
+# Interface: ParamPart
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L71)
+
+A param: `:name`, `(\d+)`, or `*`.
+
+An anonymous param carries no `name`. URLPattern numbers such a group from `0`, and
+this library reports it to no machine — see [ParsedPattern.params](ParsedPattern.md#property-params).
+
+## Properties
+
+| Property                                    | Modifier   | Type                                                    | Description                                                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                                                                   |
+| ------------------------------------------- | ---------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-groupname"></a> `groupName` | `readonly` | `string` \| `null`                                      | The name that URLPattern compiles, with each hyphen rewritten to an underscore, or `null` for an anonymous param. The rewrite happens ONE time, here, and [ParsedPattern.normalized](ParsedPattern.md#property-normalized) carries the same characters. A caller that needs the group name of a param reads this field, and it rewrites nothing of its own. | [packages/play-pattern/src/pattern-grammar.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L83) |
+| <a id="property-kind"></a> `kind`           | `readonly` | `"param"`                                               | -                                                                                                                                                                                                                                                                                                                                                           | [packages/play-pattern/src/pattern-grammar.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L72) |
+| <a id="property-modifier"></a> `modifier`   | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md) | -                                                                                                                                                                                                                                                                                                                                                           | [packages/play-pattern/src/pattern-grammar.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L88) |
+| <a id="property-name"></a> `name`           | `readonly` | `string` \| `null`                                      | The declared name, with each hyphen kept, or `null` for an anonymous param.                                                                                                                                                                                                                                                                                 | [packages/play-pattern/src/pattern-grammar.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L74) |
+| <a id="property-prefix"></a> `prefix`       | `readonly` | `string`                                                | The `/` that the param absorbed from the literal before it, or `""`.                                                                                                                                                                                                                                                                                        | [packages/play-pattern/src/pattern-grammar.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L87) |
+| <a id="property-regexp"></a> `regexp`       | `readonly` | `string` \| `null`                                      | The source of the constraint of `:id(\d+)`, or `null` when the param declares none.                                                                                                                                                                                                                                                                         | [packages/play-pattern/src/pattern-grammar.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L85) |

package/api/@xmachines/play-url/index/interfaces/ParseOptions.md

@@ -0,0 +1,24 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ParseOptions
+
+# Interface: ParseOptions
+
+Defined in: [packages/play-pattern/src/cache.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L34)
+
+The options that every read of the pattern language takes.
+
+It is ONE field today, and it is an object rather than a positional argument so that a
+caller holds one object and hands it to every call — `parsePattern`, `buildPath`,
+`getCompiledPattern`, `findRouteByPath`, a route map and a bridge all take it, and
+`CompileOptions` and `RouteMapOptions` extend it with the caches of their own layer. A
+positional argument gave each layer a different position to remember.
+
+## Extended by
+
+- [`CompileOptions`](CompileOptions.md)
+- [`FrameworkParamsSource`](FrameworkParamsSource.md)
+
+## Properties
+
+| Property                                           | Modifier   | Type                                                                     | Description                                                                                                              | Defined in                                                                                                                               |
+| -------------------------------------------------- | ---------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-patterncache"></a> `patternCache?` | `readonly` | [`PatternCache`](PatternCache.md)\<[`ParsedPattern`](ParsedPattern.md)\> | The cache of the PARSE of a pattern. The default is the cache that this package shares with every caller of the process. | [packages/play-pattern/src/cache.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L40) |