@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/play-tanstack-solid-router/interfaces/RoutableActor.md

@@ -0,0 +1,72 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / RoutableActor
+
+# Interface: RoutableActor
+
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L392)
+
+The minimal actor interface that `RouterBridgeBase` and every framework router
+adapter require.
+
+It names `send` itself, and it therefore gives `RouterBridgeBase.actor.send` a type that
+accepts a `PlayRouteEvent` directly. That removes the unsafe cast
+`(actor.send as (e: PlayRouteEvent) => void)`.
+
+It is [Routable](../../play-router/index/interfaces/Routable.md) with `send`. The two members of the capability are declared once,
+in `Routable`, and this interface extends it. A copy of them here drifts the day that
+one of the two files changes.
+
+**It names the view NOWHERE. Routing implies no rendering.** No file of this package,
+and no file of any of the eight router adapters, ever reads `currentView`. A provider
+whose renderer callback reads the view binds its own `TActor`, and a constraint keeps
+the concrete type of the actor whole, so that callback still reads the exact spec of
+that actor.
+
+Every `PlayActor` of `@xmachines/play-actor` that also implements `Routable`, and whose
+event union holds `PlayRouteEvent`, satisfies this interface structurally. A machine
+that declares no route event does NOT satisfy it, and that refusal is correct: a bridge
+cannot navigate an actor that receives no route event.
+
+## Example
+
+```typescript
+import type { RoutableActor } from "@xmachines/play-router";
+
+class MyBridge extends RouterBridgeBase {
+	constructor(actor: RoutableActor, routeMap: RouteMap) {
+		super(actor, routeMap);
+	}
+}
+```
+
+## Extends
+
+- [`Routable`](../../play-router/index/interfaces/Routable.md)
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                         | Inherited from                                                                                                                                      | Defined in                                                                                                                      |
+| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | [`Routable`](../../play-router/index/interfaces/Routable.md).[`currentRoute`](../../play-router/index/interfaces/Routable.md#property-currentroute) | [play-router/src/types.ts:354](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L354) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | [`Routable`](../../play-router/index/interfaces/Routable.md).[`initialRoute`](../../play-router/index/interfaces/Routable.md#property-initialroute) | [play-router/src/types.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L355) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [play-router/src/types.ts:394](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L394)
+
+Sends a route navigation event to the actor.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-tanstack-solid-router/interfaces/RouteMapOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/types.ts:567](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L567)
 
 The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map.ts#L21) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                      |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/types.ts:579](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L579) |

package/api/@xmachines/play-tanstack-solid-router/interfaces/RouteMapping.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L54)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L54)
 
 One entry of the map between a state ID and a path.
 
@@ -24,5 +24,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
 | --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L58) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L56) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L56) |

package/api/@xmachines/play-tanstack-solid-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L359)
+Defined in: [play-router/src/types.ts:438](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L438)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
@@ -56,7 +56,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L376)
+Defined in: [play-router/src/types.ts:455](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L455)
 
 Connects the router bridge to the Actor
 
@@ -86,7 +86,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L392)
+Defined in: [play-router/src/types.ts:471](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/types.ts#L471)
 
 Disconnects the router bridge from the Actor
 

package/api/@xmachines/play-tanstack-solid-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -1,15 +1,24 @@
 [API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / PlayRouterBridgeConstructor
 
-# Type Alias: PlayRouterBridgeConstructor\<TRouter\>
+# Type Alias: PlayRouterBridgeConstructor\<TRouter, TActor\>
 
 ```ts
-type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap, options?) => RouterBridge;
+type PlayRouterBridgeConstructor<TRouter, TActor> = (
+	router,
+	actor,
+	routeMap,
+	options?,
+) => RouterBridge;
 ```
 
-Defined in: [play-router/src/provider-lifecycle.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L103)
+Defined in: [play-router/src/provider-lifecycle.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L107)
 
 The constructor shape that a bridge class must satisfy for a provider factory: `(router, actor, routeMap, options?) → RouterBridge`.
 
+`TActor` carries the actor type of the caller through to the constructor, so the spec
+type of that actor reaches the bridge whole. A bridge that reads no spec binds nothing
+and receives the default.
+
 The return type is `RouterBridge`, the published contract of a bridge, so a
 consumer bridge of its own keeps compiling. Every bridge on `RouterBridgeBase` also
 satisfies `MountableRouterBridge`, and the provider finds that mount API at run
@@ -18,16 +27,17 @@ existed.
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `TRouter`      |
+| Type Parameter                                                       | Default type                                      |
+| -------------------------------------------------------------------- | ------------------------------------------------- |
+| `TRouter`                                                            | -                                                 |
+| `TActor` _extends_ [`RoutableActor`](../interfaces/RoutableActor.md) | [`RoutableActor`](../interfaces/RoutableActor.md) |
 
 ## Parameters
 
 | Parameter  | Type                                                                     |
 | ---------- | ------------------------------------------------------------------------ |
 | `router`   | `TRouter`                                                                |
-| `actor`    | [`PlayActor`](../interfaces/PlayActor.md)                                |
+| `actor`    | `TActor`                                                                 |
 | `routeMap` | [`RouteMap`](../classes/RouteMap.md)                                     |
 | `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) |
 

package/api/@xmachines/play-tanstack-solid-router/type-aliases/PlayRouterProviderBaseProps.md

@@ -10,7 +10,7 @@ type PlayRouterProviderBaseProps<TRouter, TActor> = PlayRouterProviderBaseProps<
 >;
 ```
 
-Defined in: [play-tanstack-solid-router/src/create-play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L34)
+Defined in: [play-tanstack-solid-router/src/create-play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-solid-router/src/create-play-router-provider.tsx#L34)
 
 The props of a Solid `PlayRouterProvider`.
 
@@ -20,7 +20,7 @@ bound to `JSX.Element`. See `PlayRouterProviderBaseProps` of
 
 ## Type Parameters
 
-| Type Parameter                                               | Default type                              |
-| ------------------------------------------------------------ | ----------------------------------------- |
-| `TRouter`                                                    | -                                         |
-| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) | [`PlayActor`](../interfaces/PlayActor.md) |
+| Type Parameter                                                       | Default type                                      |
+| -------------------------------------------------------------------- | ------------------------------------------------- |
+| `TRouter`                                                            | -                                                 |
+| `TActor` _extends_ [`RoutableActor`](../interfaces/RoutableActor.md) | [`RoutableActor`](../interfaces/RoutableActor.md) |

package/api/@xmachines/play-tanstack-solid-router/type-aliases/TanStackRouterInstance.md

@@ -6,4 +6,4 @@
 type TanStackRouterInstance = ConstructorParameters<typeof TanStackSolidRouterBridge>[0];
 ```
 
-Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L23)
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L21)

package/api/@xmachines/play-tanstack-solid-router/type-aliases/TanStackRouterLike.md

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L39)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L39)
 
 The type-only interface of the TanStack Router surface that
 `TanStackRouterBridgeBase` uses. An instance of `@tanstack/react-router` and an
@@ -20,7 +20,7 @@ instance of `@tanstack/solid-router` both satisfy it.
 history: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L72)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L72)
 
 #### location
 
@@ -69,7 +69,7 @@ subscribe(handler): () => void;
 optional options?: object;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L58)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L58)
 
 The options of the router. The bridge reads `parseSearch` only.
 
@@ -103,7 +103,7 @@ optional parseSearch(search): Record<string, unknown>;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L71)
 
 Runs the TanStack route matching and the loaders again for the current location.
 This method is optional. The bridge calls it after every navigation. The matching
@@ -128,7 +128,7 @@ bridge then synchronizes synchronously.
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L48)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L48)
 
 Navigates to a location. `search` carries the query of the target.
 

package/api/@xmachines/play-tanstack-solid-router/variables/PlayRouterProvider.md

@@ -6,7 +6,7 @@
 const PlayRouterProvider: <TActor>(props) => any;
 ```
 
-Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L43)
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L41)
 
 Connects a `PlayerActor` to TanStack Solid Router. It keeps the actor state and the
 browser URL in step, in both directions.
@@ -18,9 +18,9 @@ the `props` accessor of Solid is reactive already.
 
 ## Type Parameters
 
-| Type Parameter                                               |
-| ------------------------------------------------------------ |
-| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) |
+| Type Parameter                                                       |
+| -------------------------------------------------------------------- |
+| `TActor` _extends_ [`RoutableActor`](../interfaces/RoutableActor.md) |
 
 ## Parameters
 

package/api/@xmachines/play-url/README.md

@@ -0,0 +1,69 @@
+[API](../../README.md) / @xmachines/play-url
+
+# @xmachines/play-url
+
+The URL language of the XMachines Play Architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-url)
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-url
+```
+
+**Peer dependencies.** Install them with the package:
+
+```bash
+pnpm add @xmachines/play
+```
+
+[`@xmachines/play-router`](../play-router/README.md) depends on this package already. Install it directly when you read the grammar yourself.
+
+## Overview
+
+`URLPattern` is the pattern language of XMachines, and this package reads it in ONE place: the parser, the compilation of a pattern against the native API or the polyfill, a base path with its `:param` substitution, and the normalization of the params that a framework router reports.
+
+It knows nothing of a state machine, of a route tree, or of a router bridge. Those live in [`@xmachines/play-router`](../play-router/README.md), which reads this package.
+
+**The package exists because BOTH directions need the grammar.** A URL becomes a state through the match of `@xmachines/play-router`, and a state becomes a URL through the substitution of the routing capability of [`@xmachines/play-xstate`](../play-xstate/README.md). One parser answers both, and neither of those packages depends on the other.
+
+| Export                                               | Description                                                                   |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `parsePattern`                                       | The whole pathname grammar of URLPattern, read one time and cached            |
+| `getIndexKey`                                        | The bucket key of a concrete path                                             |
+| `URLPattern`, `getCompiledPattern`                   | The native API where a runtime carries it, and the polyfill where it does not |
+| `normalizeBasePath`, `joinBasePath`, `stripBasePath` | A URL prefix that a host owns, with its `:param` substitution                 |
+| `resolveFrameworkParams`                             | The params of a framework router, reconciled with the pattern                 |
+
+### The error classes carry a subpath of their own
+
+`@xmachines/play-url/errors` exports the three error classes, and the root barrel
+exports none of them. Every package of this workspace that raises an error publishes
+it the same way: `@xmachines/play/errors`, `@xmachines/play-router/errors`,
+`@xmachines/play-view/errors`, `@xmachines/play-vue-router/errors` and
+`@xmachines/play-xstate/errors`. A module
+that needs a `catch` to name a fault therefore loads the classes alone, with no
+pattern parser and no base path:
+
+```typescript
+import { InvalidBasePathError } from "@xmachines/play-url/errors";
+```
+
+### The API is always present
+
+This package carries [`urlpattern-polyfill`](https://github.com/kenchris/urlpattern-polyfill) as an ordinary dependency. It uses the native `URLPattern` when the runtime has one, and the polyfill when it does not. **Install nothing, and load nothing.**
+
+## Documentation
+
+- [Routing guide](../../../guides/routing.md) — the pattern grammar, one time, for every adapter
+- [Architecture](../../../contributing/architecture.md)
+
+## License
+
+MIT
+
+## Modules
+
+- [errors](errors/README.md)
+- [index](index/README.md)

package/api/@xmachines/play-url/errors/README.md

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-url](../README.md) / errors
+
+# errors
+
+The errors of the URL language.
+
+Each one names a fault in a PATTERN, in a base path, or in a param of one — and no fault
+of a route tree, of a machine, or of a bridge. Those live in `@xmachines/play-router`.
+
+Every class extends `PlayError` of `@xmachines/play`, so a consumer sorts an error with
+one `instanceof` for the whole architecture.
+
+## Classes
+
+- [InvalidBasePathError](classes/InvalidBasePathError.md)
+- [InvalidRoutePatternError](classes/InvalidRoutePatternError.md)
+- [MissingBasePathParamError](classes/MissingBasePathParamError.md)

package/api/@xmachines/play-url/errors/classes/InvalidBasePathError.md

@@ -0,0 +1,200 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [errors](../README.md) / InvalidBasePathError
+
+# Class: InvalidBasePathError
+
+Defined in: [packages/play-url/src/errors.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/errors.ts#L99)
+
+Thrown when a `basePath` option resolves to one concrete URL prefix never.
+
+A bridge writes a real browser URL from its prefix, so every segment must hold
+exactly one value. A wildcard segment (`*`), an optional segment (`:section?`), a
+nameless `:` segment, a query string, and a hash fragment each describe a SET of
+prefixes instead, or no prefix at all. A `$param` segment is the route-param
+syntax of TanStack Router: a base path writes a param as `:param`, and it takes
+the value of that param from `basePathParams`.
+
+**How to fix it:** mount on the prefix itself, and let the machine own the rest.
+For the splat route `/$machineId/play/$` of TanStack, the base path is
+`"/:machineId/play"` with `basePathParams: { machineId }`.
+
+**Error code:** `PLAY_ROUTER_INVALID_BASE_PATH`
+
+## Example
+
+```typescript
+import { InvalidBasePathError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.setBasePath("/:machineId/play/*");
+} catch (err) {
+	if (err instanceof InvalidBasePathError) {
+		console.error(`Bad base path: "${err.basePath}"`, err.message);
+	}
+}
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new InvalidBasePathError(basePath, reason): InvalidBasePathError;
+```
+
+Defined in: [packages/play-url/src/errors.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/errors.ts#L103)
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `basePath` | `string` |
+| `reason`   | `string` |
+
+#### Returns
+
+`InvalidBasePathError`
+
+#### Overrides
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`constructor`](../../../play/errors/classes/PlayError.md#constructor)
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                           |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-basepath"></a> `basePath`               | `readonly` | `string`  | The `basePath` option of the refusal, exactly as the caller gave it.                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                                                | [packages/play-url/src/errors.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/errors.ts#L101) |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/PlayError.md#property-cause)                     | -                                                                                                                                    |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L76)           |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                                    |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/PlayError.md#property-name)                       | -                                                                                                                                    |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L66)           |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/PlayError.md#property-stack)                     | -                                                                                                                                    |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                                    |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: `@types/node`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack; // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+	b();
+}
+
+function b() {
+	c();
+}
+
+function c() {
+	// Create an error without stack trace to avoid calculating the stack trace twice.
+	const { stackTraceLimit } = Error;
+	Error.stackTraceLimit = 0;
+	const error = new Error();
+	Error.stackTraceLimit = stackTraceLimit;
+
+	// Capture the stack trace above function b
+	Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+	throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`captureStackTrace`](../../../play/errors/classes/PlayError.md#capturestacktrace)
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Defined in: `typescript`
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`isError`](../../../play/errors/classes/PlayError.md#iserror)
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: `@types/node`
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`prepareStackTrace`](../../../play/errors/classes/PlayError.md#preparestacktrace)