@xmachines/docs 3.0.0 → 4.0.0

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

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

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

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getRequiredPatternParamNames
+
+# Function: getRequiredPatternParamNames()
+
+```ts
+function getRequiredPatternParamNames(pattern): string[];
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L52)
+
+The names of every param the pattern REQUIRES, so an optional one is left out.
+
+A param is optional when its own modifier is `?` or `*`, and when EVERY group above it
+carries one of the two. `?` alone was the test before, and it read `/files/:path*` and
+`/books{/:id}?` as required patterns: a path that fills neither then counted as a gap,
+the pick was discarded, and a correct parse from Vue Router or SolidJS Router went with
+it. That is the same class of defect as the all-optional bug of !133, for the modifiers
+that the fix did not cover.
+
+An optional segment that did not match has no value, and a framework reports none. That
+is a complete answer and not a partial one, so a MIXED pattern such as
+`/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
+
+A pattern whose params are ALL optional reports nothing at all, which reads the same as
+"the framework matched another route", so [pickOwnParams](pickOwnParams.md) falls back for it.
+[resolveFrameworkParams](resolveFrameworkParams.md) settles that case from the PATH instead.
+
+## Parameters
+
+| Parameter | Type     | Description                                            |
+| --------- | -------- | ------------------------------------------------------ |
+| `pattern` | `string` | A route pattern, for example `/profile/:userId/:tab?`. |
+
+## Returns
+
+`string`[]
+
+The required names, in the order that the pattern declares them. A fresh
+array, because `parsePattern` caches the parse that it reads.

package/api/@xmachines/play-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:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L120)
+
+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
+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/isParameterizedPattern.md

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / isParameterizedPattern
+
+# Function: isParameterizedPattern()
+
+```ts
+function isParameterizedPattern(pattern): boolean;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L97)
+
+Tells you if a route path needs a URLPattern match, and is not a concrete URL.
+
+A pattern holds a param — `:name`, `(\d+)` or `*` — or a `{…}` group, or an escape.
+Each of them needs a match, and each of them carries no concrete value, so the code
+can push such a path to a browser URL never.
+
+This function is THE single source of truth of the question "is this path a pattern?".
+`RouteMap` uses it for its decision between the static map and the index of the pattern
+buckets, and `extractRouteParams` uses it to answer `{}` for a literal path. A CONCRETE
+path asks [holdsUnsubstitutedParam](holdsUnsubstitutedParam.md) instead, and never this function.
+
+The answer comes from the parse, and not from a search for a `:` or a `*`. That search
+called `/a{/b}?/c` a static path, and `RouteMap` then put it in the exact-match map,
+where the path `/a/c` reached it never.
+
+## Parameters
+
+| Parameter | Type     | Description                                                                                 |
+| --------- | -------- | ------------------------------------------------------------------------------------------- |
+| `pattern` | `string` | The string of a URL path or of a route pattern, for example `/profile/:userId` or `/docs/*` |
+
+## Returns
+
+`boolean`
+
+`true` when the path needs a URLPattern match

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:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L302)
 
 Adds the base path to an outbound path of the machine.
 

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:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L130)
 
 Normalizes a base path, and it substitutes no `:param` segment of that path.
 

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

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / normalizeParamNames
+
+# Function: normalizeParamNames()
+
+```ts
+function normalizeParamNames(path): string;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L139)
+
+Normalizes a route path, so that each of its parameter names is a valid URLPattern
+identifier.
+
+URLPattern requires a valid JS identifier as a parameter name, and such an identifier
+holds no hyphen. Therefore the function replaces a name with a hyphen, for example
+`:cat-id`, with the equivalent name with an underscore (`:cat_id`), for the compilation
+step of URLPattern. A caller that needs the values of the captured groups, and not a
+test of the match alone, must map each normalized group name back to the original param
+name with [getNormalizedParamNameMap](getNormalizedParamNameMap.md).
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+## Returns
+
+`string`
+
+## Example
+
+```ts
+normalizeParamNames("/docs/:cat-id/:page-num?");
+// → "/docs/:cat_id/:page_num?"
+```

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

@@ -0,0 +1,27 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / parsePattern
+
+# Function: parsePattern()
+
+```ts
+function parsePattern(pattern): 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)
+
+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`. |
+
+## 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:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L84)
 
 Keeps the entries of `params` whose name the pattern of the machine declares, and
 only when the result covers EVERY name of that pattern.
@@ -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:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L180)
 
 Resolves a base path and its params to the concrete prefix that a browser URL
 carries.

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(__namedParameters): 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)
+
+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                                                              |
+| ------------------- | ----------------------------------------------------------------- |
+| `__namedParameters` | [`FrameworkParamsSource`](../interfaces/FrameworkParamsSource.md) |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+The path parameters of the machine route, or `{}`.

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:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L276)
 
 Removes the base path from an inbound location of the router.
 

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

@@ -0,0 +1,28 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / BasePathOptions
+
+# 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)
+
+The base-path options that every router bridge, `connectRouter` function, and
+`PlayRouterProvider` component accepts.
+
+## Example
+
+```typescript
+// A host that mounts a machine under a route it resolved in a loader
+connectRouter({
+	actor,
+	router,
+	routeMap,
+	basePath: "/:machineId/play",
+	basePathParams: { machineId },
+});
+```
+
+## 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.                                                 | [packages/play-url/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L58) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [packages/play-url/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L72) |

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

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

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-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)
+
+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) |

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-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)
+
+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) |

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-url/src/pattern-grammar.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L69)
+
+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-url/src/pattern-grammar.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L81) |
+| <a id="property-kind"></a> `kind`           | `readonly` | `"param"`                                               | -                                                                                                                                                                                                                                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L70) |
+| <a id="property-modifier"></a> `modifier`   | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md) | -                                                                                                                                                                                                                                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L86) |
+| <a id="property-name"></a> `name`           | `readonly` | `string` \| `null`                                      | The declared name, with each hyphen kept, or `null` for an anonymous param.                                                                                                                                                                                                                                                                                 | [packages/play-url/src/pattern-grammar.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L72) |
+| <a id="property-prefix"></a> `prefix`       | `readonly` | `string`                                                | The `/` that the param absorbed from the literal before it, or `""`.                                                                                                                                                                                                                                                                                        | [packages/play-url/src/pattern-grammar.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L85) |
+| <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-url/src/pattern-grammar.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L83) |

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

@@ -0,0 +1,23 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ParsedPattern
+
+# Interface: ParsedPattern
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L115)
+
+Everything that this library reads from one route pattern.
+
+## Properties
+
+| Property                                            | Modifier   | Type                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Defined in                                                                                                                                             |
+| --------------------------------------------------- | ---------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-bareform"></a> `bareForm`           | `readonly` | `string` \| `null`                                         | The path that the pattern matches when every optional part is absent, or `null` when the pattern holds a part that a path must fill. `/settings/:section?` gives `/settings`, `/a/{b}?/c` gives `/a//c`, and `/profile/:userId` gives `null`.                                                                                                                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L152) |
+| <a id="property-declarednames"></a> `declaredNames` | `readonly` | `ReadonlyMap`\<`string`, `string`\>                        | The map from each rewritten group name back to the name that the pattern declares, for example `cat_id` to `cat-id`. The map holds an entry only for a name that the rewrite changed. It is empty for most patterns, and a caller that reads a group name falls back to the name itself.                                                                                                                                                                                                | [packages/play-url/src/pattern-grammar.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L182) |
+| <a id="property-indexkey"></a> `indexKey`           | `readonly` | `string`                                                   | The key of the bucket index: the first path segment, or `"*"` when a param can stand in the first segment.                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-url/src/pattern-grammar.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L169) |
+| <a id="property-literalpath"></a> `literalPath`     | `readonly` | `string` \| `null`                                         | The ONE path that the pattern matches, with each escape resolved, or `null` when the pattern describes a SET of paths. `/users` gives `/users`, `/tags/c\+\+` gives `/tags/c++`, `/x{y}z` gives `/xyz`, and `/profile/:userId` gives `null`. A bridge writes a real browser URL from this field. The SOURCE of the pattern is no substitute for it: `/tags/c\+\+` carries two backslashes that the address bar must not hold, and a location that carries them matches the route never. | [packages/play-url/src/pattern-grammar.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L164) |
+| <a id="property-names"></a> `names`                 | `readonly` | readonly `string`[]                                        | The name of every param of [params](#property-params), in the same order. `resolveFrameworkParams` runs on EVERY navigation and it needs this list each time. The parse holds it, so a navigation allocates none. A caller that hands the array to somebody else copies it: the cache holds this one.                                                                                                                                                                                   | [packages/play-url/src/pattern-grammar.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L129) |
+| <a id="property-normalized"></a> `normalized`       | `readonly` | `string`                                                   | The pattern in the form that URLPattern compiles: each param name that holds a hyphen carries an underscore instead.                                                                                                                                                                                                                                                                                                                                                                    | [packages/play-url/src/pattern-grammar.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L174) |
+| <a id="property-parameterized"></a> `parameterized` | `readonly` | `boolean`                                                  | True when the pattern needs a URLPattern match, and false when it is a literal path. A malformed pattern reports `true`, so that it reaches the URLPattern constructor and fails there with the error of the API. A parser that called it static would send it to the exact-match map instead, where it matches nothing and reports no fault.                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:144](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L144) |
+| <a id="property-params"></a> `params`               | `readonly` | readonly [`PatternParam`](PatternParam.md)[]               | The NAMED params, in the order that the pattern declares them.                                                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-url/src/pattern-grammar.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L121) |
+| <a id="property-parts"></a> `parts`                 | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | The parts, in the order that the pattern declares them.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [packages/play-url/src/pattern-grammar.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L119) |
+| <a id="property-requirednames"></a> `requiredNames` | `readonly` | readonly `string`[]                                        | The name of every param that a path must fill, in the order of [params](#property-params). The same rule as [names](#property-names): the parse holds the array, and a navigation reads it.                                                                                                                                                                                                                                                                                             | [packages/play-url/src/pattern-grammar.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L135) |
+| <a id="property-source"></a> `source`               | `readonly` | `string`                                                   | The pattern as the caller wrote it.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-url/src/pattern-grammar.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L117) |

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

@@ -0,0 +1,15 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / PatternParam
+
+# Interface: PatternParam
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L99)
+
+One named param of a pattern, with the question that every caller asks about it.
+
+## Properties
+
+| Property                                    | Modifier   | Type      | Description                                                                                                                                                                                                                                                           | Defined in                                                                                                                                             |
+| ------------------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-groupname"></a> `groupName` | `readonly` | `string`  | The name that URLPattern compiles, for example `cat_id`.                                                                                                                                                                                                              | [packages/play-url/src/pattern-grammar.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L103) |
+| <a id="property-name"></a> `name`           | `readonly` | `string`  | The name as the pattern declares it, for example `cat-id`.                                                                                                                                                                                                            | [packages/play-url/src/pattern-grammar.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L101) |
+| <a id="property-optional"></a> `optional`   | `readonly` | `boolean` | True when a matching path can carry no value for this param. The modifier `?` and the modifier `*` make a param optional, and so does EVERY group above it that carries one of the two. The modifier `+` does not: it repeats a param that one value must still fill. | [packages/play-url/src/pattern-grammar.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L111) |

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

@@ -1,14 +1,14 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / ResolvedBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ResolvedBasePath
 
 # Interface: ResolvedBasePath
 
-Defined in: [play-router/src/base-path.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L78)
+Defined in: [packages/play-url/src/base-path.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L78)
 
 A base path that is ready for a use in both directions.
 
 ## Properties
 
-| Property                              | Modifier   | Type                           | Description                                                                                                                                                                     | Defined in                                                                                                                            |
-| ------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-params"></a> `params` | `readonly` | `Record`\<`string`, `string`\> | The values of each `:param` of the prefix, for the `params` of a `play.route` event. The object is empty for a prefix without a param, and for a pattern that nothing resolved. | [play-router/src/base-path.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L89) |
-| <a id="property-path"></a> `path`     | `readonly` | `string`                       | The normalized prefix: it starts with `/`, it carries no trailing `/`, and it holds no duplicate slash. The empty string means "no prefix".                                     | [play-router/src/base-path.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L83) |
+| Property                              | Modifier   | Type                           | Description                                                                                                                                                                     | Defined in                                                                                                                               |
+| ------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-params"></a> `params` | `readonly` | `Record`\<`string`, `string`\> | The values of each `:param` of the prefix, for the `params` of a `play.route` event. The object is empty for a prefix without a param, and for a pattern that nothing resolved. | [packages/play-url/src/base-path.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L89) |
+| <a id="property-path"></a> `path`     | `readonly` | `string`                       | The normalized prefix: it starts with `/`, it carries no trailing `/`, and it holds no duplicate slash. The empty string means "no prefix".                                     | [packages/play-url/src/base-path.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L83) |

package/api/@xmachines/play-url/index/type-aliases/PatternModifier.md

@@ -0,0 +1,11 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / PatternModifier
+
+# Type Alias: PatternModifier
+
+```ts
+type PatternModifier = "" | "?" | "+" | "*";
+```
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L54)
+
+The modifier of a part. `""` means that the part carries none.