@xmachines/docs 4.0.0 → 5.0.0

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

@@ -0,0 +1,46 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / buildPath
+
+# Function: buildPath()
+
+```ts
+function buildPath(pattern, params?, options?): PathBuildResult;
+```
+
+Defined in: [packages/play-pattern/src/pattern-grammar.ts:713](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L713)
+
+Builds the path that a pattern describes, with each param filled from `params`.
+
+This is the OUTBOUND half of the language, and it reads the same parse as the match.
+The walk drops an optional part that has no value TOGETHER with the `/` that the part
+absorbed, which is the prefix rule of the module comment: `/settings/:section?` builds
+`/settings`, and not `/settings/`.
+
+The function reports a fault through its return value, and it throws never. The
+`reason` field names the fault: `missing` for a param that needs a value and has none,
+and `unresolvable` for a param that carries a value no path can hold. A caller raises
+the error of its own layer — `@xmachines/play-xstate` raises `MissingRouteParamError`
+for the first one and `InvalidRouteParamError` for the second.
+
+## Parameters
+
+| Parameter  | Type                                            | Description                                                           |
+| ---------- | ----------------------------------------------- | --------------------------------------------------------------------- |
+| `pattern`  | `string`                                        | The route pattern, for example `/profile/:userId`.                    |
+| `params`   | [`PathParams`](../type-aliases/PathParams.md)   | The value of each param, keyed by the name that the pattern declares. |
+| `options?` | [`ParseOptions`](../interfaces/ParseOptions.md) | -                                                                     |
+
+## Returns
+
+[`PathBuildResult`](../type-aliases/PathBuildResult.md)
+
+The path, or the reason that stopped the walk with the param that carries it.
+
+## Example
+
+```typescript
+buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
+buildPath("/settings/:section?", {}); // { ok: true, path: "/settings" }
+buildPath("/tags/c\\+\\+", {}); // { ok: true, path: "/tags/c++" }
+buildPath("/profile/:userId", {}); // { ok: false, reason: "missing", missing: "userId" }
+buildPath("/files/:name", { name: ".." }); // { ok: false, reason: "unresolvable", … }
+```

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

@@ -6,7 +6,7 @@
 function cleanFrameworkParams(params): Record<string, string>;
 ```
 
-Defined in: [packages/play-url/src/framework-params.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L148)
+Defined in: [packages/play-url/src/framework-params.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L107)
 
 The params of a framework router, in the shape that [pickOwnParams](pickOwnParams.md) reads.
 

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

@@ -0,0 +1,47 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / createPatternCache
+
+# Function: createPatternCache()
+
+```ts
+function createPatternCache<V>(maxSize?): PatternCache<V>;
+```
+
+Defined in: [packages/play-pattern/src/cache.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L85)
+
+Builds a cache that forgets its least recently used entries.
+
+## The algorithm
+
+Two maps, and no list. `recent` takes every write. When a write fills `recent`, it
+becomes `old` and a new `recent` opens, which drops the previous `old` whole. A read of
+a key of `old` moves the entry into `recent`, and THAT is what makes the eviction an
+LRU one rather than a FIFO one: an entry that every lookup reads moves forward, and an
+entry that nothing reads falls out with the map that holds it.
+
+The cache therefore holds between `maxSize` and `2 * maxSize` entries, and it does no
+bookkeeping for a read that hits `recent`.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `V`            |
+
+## Parameters
+
+| Parameter | Type     | Default value | Description                                                                                                                                                                                                          |
+| --------- | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxSize` | `number` | `500`         | The number of entries that `recent` holds. It is `1` at the least, and the default is `500`. A value that is not a finite number reads as the default, so a cache with no eviction at all cannot happen by accident. |
+
+## Returns
+
+[`PatternCache`](../interfaces/PatternCache.md)\<`V`\>
+
+A cache. It is not shared: each call builds one.
+
+## Example
+
+```typescript
+const cache = createPatternCache<ParsedPattern>(50);
+parsePattern("/profile/:userId", { patternCache: cache });
+```

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

@@ -6,7 +6,7 @@
 function getCandidates<T>(patternBuckets, indexKey): T[];
 ```
 
-Defined in: [packages/play-url/src/url-pattern-utils.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L242)
+Defined in: [packages/play-url/src/url-pattern-utils.ts:214](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/url-pattern-utils.ts#L214)
 
 Joins the bucket of the named segment and the wildcard bucket of one index key.
 The order of the insertion stays, through the `order` field.

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

@@ -3,24 +3,25 @@
 # Function: getCompiledPattern()
 
 ```ts
-function getCompiledPattern(pattern): URLPatternLike;
+function getCompiledPattern(pattern, options?): URLPatternLike;
 ```
 
-Defined in: [packages/play-url/src/url-pattern-utils.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L216)
+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.
 
-[normalizeParamNames](normalizeParamNames.md) normalizes the pattern before the compilation. A param name
+[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
-[getNormalizedParamNameMap](getNormalizedParamNameMap.md).
+[ParsedPattern.declaredNames](../interfaces/ParsedPattern.md#property-declarednames).
 
 ## Parameters
 
-| Parameter | Type     | Description                                                     |
-| --------- | -------- | --------------------------------------------------------------- |
-| `pattern` | `string` | The string of the route pattern, for example `/profile/:userId` |
+| 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
 

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

@@ -6,7 +6,7 @@
 function getIndexKey(path): string;
 ```
 
-Defined in: [packages/play-url/src/pattern-grammar.ts:199](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L199)
+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.
 

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

@@ -6,11 +6,11 @@
 function holdsUnsubstitutedParam(pathname): boolean;
 ```
 
-Defined in: [packages/play-url/src/url-pattern-utils.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L120)
+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 [isParameterizedPattern](isParameterizedPattern.md), and it needs a
+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`,

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-url/index/functions/joinBasePath.md

@@ -6,7 +6,7 @@
 function joinBasePath(basePath, path): string;
 ```
 
-Defined in: [packages/play-url/src/base-path.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L302)
+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-url/index/functions/normalizeBasePath.md

@@ -6,7 +6,7 @@
 function normalizeBasePath(basePath?): string;
 ```
 
-Defined in: [packages/play-url/src/base-path.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L130)
+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

@@ -3,10 +3,10 @@
 # Function: parsePattern()
 
 ```ts
-function parsePattern(pattern): ParsedPattern;
+function parsePattern(pattern, options?): ParsedPattern;
 ```
 
-Defined in: [packages/play-url/src/pattern-grammar.ts:262](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L262)
+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.
 
@@ -16,9 +16,10 @@ constructor and keeps every derived answer on the safe side.
 
 ## Parameters
 
-| Parameter | Type     | Description                                        |
-| --------- | -------- | -------------------------------------------------- |
-| `pattern` | `string` | The route pattern, for example `/profile/:userId`. |
+| Parameter  | Type                                            | Description                                        |
+| ---------- | ----------------------------------------------- | -------------------------------------------------- |
+| `pattern`  | `string`                                        | The route pattern, for example `/profile/:userId`. |
+| `options?` | [`ParseOptions`](../interfaces/ParseOptions.md) | -                                                  |
 
 ## Returns
 

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

@@ -6,7 +6,7 @@
 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)
+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.

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

@@ -6,7 +6,7 @@
 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)
+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

@@ -3,10 +3,10 @@
 # Function: resolveFrameworkParams()
 
 ```ts
-function resolveFrameworkParams(__namedParameters): Record<string, string>;
+function resolveFrameworkParams(source): Record<string, string>;
 ```
 
-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)
+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.
 
@@ -38,9 +38,9 @@ one.
 
 ## Parameters
 
-| Parameter           | Type                                                              |
-| ------------------- | ----------------------------------------------------------------- |
-| `__namedParameters` | [`FrameworkParamsSource`](../interfaces/FrameworkParamsSource.md) |
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `source`  | [`FrameworkParamsSource`](../interfaces/FrameworkParamsSource.md) |
 
 ## Returns
 

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-url/index/functions/stripBasePath.md

@@ -6,7 +6,7 @@
 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)
+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-url/index/interfaces/BasePathOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: BasePathOptions
 
-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)
+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.
@@ -24,5 +24,5 @@ connectRouter({
 
 | 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) |
+| <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

@@ -2,17 +2,22 @@
 
 # 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)
+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                                   | 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) |
+| 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
 
@@ -22,7 +27,7 @@ What [resolveFrameworkParams](../functions/resolveFrameworkParams.md) needs from
 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)
+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.
 
@@ -38,7 +43,7 @@ The URLPattern extraction of the base class, read lazily.
 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)
+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.
 

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

@@ -2,14 +2,14 @@
 
 # Interface: GroupPart
 
-Defined in: [packages/play-url/src/pattern-grammar.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L90)
+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-url/src/pattern-grammar.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L91) |
-| <a id="property-modifier"></a> `modifier` | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md)    | [packages/play-url/src/pattern-grammar.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L93) |
-| <a id="property-parts"></a> `parts`       | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | [packages/play-url/src/pattern-grammar.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L92) |
+| 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

@@ -2,13 +2,13 @@
 
 # Interface: LiteralPart
 
-Defined in: [packages/play-url/src/pattern-grammar.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L57)
+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-url/src/pattern-grammar.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L58) |
-| <a id="property-text"></a> `text` | `readonly` | `string`    | The characters that a path must carry, for example `/settings`. | [packages/play-url/src/pattern-grammar.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L60) |
+| 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) |