@xmachines/docs 2.2.0 → 4.0.0

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

@@ -4,41 +4,29 @@
 
 Route tree extraction from XState v5 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-router)
+[![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-router)
 
 This package extracts the routes from a machine graph and looks them up in both directions. The Actor therefore keeps the authority over the navigation.
 
+> **Browser floor: Chrome 110, Firefox 115, Safari 16.4.** This package calls the ES2023
+> change-by-copy array methods, so a browser below that floor throws
+> `TypeError: ... is not a function` at the extraction of the routes. The root README
+> carries the table.
+
 ## Installation
 
 ```bash
-pnpm add xstate@^5.31.0
+pnpm add xstate@^5.33.0
 pnpm add @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^5.31.0 — XState v5 state machine runtime
-
-**URLPattern polyfill (Node.js < 24 / older browsers):**
-
-`@xmachines/play-router` matches each dynamic route with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). URLPattern is native in Node.js 24+ and in a modern browser (Chrome 95+, Firefox 117+, Safari 16.4+).
-
-In an environment without the native API, load a polyfill **before** you import this package:
-
-```typescript
-// Entry point — must run before any @xmachines/play-router import
-import "urlpattern-polyfill";
-```
-
-Install the polyfill:
-
-```bash
-pnpm add urlpattern-polyfill
-```
+- `xstate` ^5.33.0 — XState v5 state machine runtime (an OPTIONAL peer: the `@xmachines/play-router/xstate` subpath alone reads it)
 
-`urlpattern-polyfill` is an optional peer dependency. A package manager does not install it for you. Install it and load it yourself when your runtime has no native URLPattern.
+**URLPattern:** this package matches each route with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). It uses the native API when the runtime has one, and it falls back to `urlpattern-polyfill`, which it carries as an ordinary dependency. **You install nothing and you load nothing.**
 
-**When you need it:** `RouteMap` compiles each parameterized route in its CONSTRUCTOR, and it throws a `URLPatternUnavailableError` there when no URLPattern is available. One route that holds a `:param` or a `*` therefore makes the polyfill a startup requirement on such a runtime. A route map whose paths are all static needs URLPattern never.
+The [routing guide](../../../guides/routing.md) states the pattern language: the forms, the modifiers, the prefix rule, and the one divergence from the standard.
 
 ## Usage
 
@@ -46,7 +34,7 @@ pnpm add urlpattern-polyfill
 
 ```typescript
 import { createMachine } from "xstate";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
+import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
 
 const machine = createMachine({
 	id: "app",
@@ -294,7 +282,7 @@ To register the routes of the machine in a host router that declares real route
 objects, ask for the list — and drop it again when the machine unloads:
 
 ```typescript
-import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router";
+import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
 
 const tree = extractMachineRoutes(machine);
 
@@ -317,25 +305,25 @@ event always carries the prefixed form.
 > matched a route of the HOST by construction, because the machine owns the suffix of
 > the path only. Those params therefore describe the route of the machine never, even
 > when a name collides — a collision carries the value of the HOST. Both adapters
-> resolve each param from the stripped path with `URLPattern` instead, and they
-> therefore need a polyfill on an older runtime when they are mounted.
+> resolve each param from the stripped path with `URLPattern` instead.
 >
-> Without a prefix both adapters keep the parse of their framework, with its decoding
-> and with no polyfill, but restricted to the names that the pattern of the machine
-> declares. A splat of a catch-all, and a param of a wrapper route, reach the actor
-> never.
+> Without a prefix both adapters keep the parse of their framework, with its decoding,
+> but restricted to the names that the pattern of the machine declares. A splat of a
+> catch-all, and a param of a wrapper route, reach the actor never. A name that the
+> pattern makes OPTIONAL is covered whether the framework reports it or not: a part that
+> did not match has no value, and that is a complete answer.
 >
-> A location that fills NO optional segment reaches URLPattern never. `/settings` is the
-> bare form of `/settings/:section?`, so the params are `{}`, and the adapters read that
-> from the path alone rather than from their framework. The route map that HOLDS that
-> pattern still needed URLPattern when it was built.
+> A location that fills NO optional part runs no match at all. `/settings` is the bare
+> form of `/settings/:section?`, so the params are `{}`, and the adapters read that from
+> the path alone rather than from their framework.
 
 ### How to write a `RouterBridgeBase` adapter
 
 Extend `RouterBridgeBase`, then implement the three abstract methods for your framework:
 
 ```typescript
-import { RouterBridgeBase, createRouteMap } from "@xmachines/play-router";
+import { RouterBridgeBase } from "@xmachines/play-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 import type { RoutableActor } from "@xmachines/play-router";
 
 // Shape of your framework's router — adjust to its real API
@@ -393,13 +381,14 @@ bridge.disconnect();
 
 ### Route Extraction
 
-| Export                                   | Description                                                                       |
-| ---------------------------------------- | --------------------------------------------------------------------------------- |
-| `extractMachineRoutes(machine)`          | Converts an XState machine into a `RouteTree` with the state ID ↔ path maps       |
-| `createRouteMap(machine, options?)`      | Builds a `RouteMap` directly from a machine. An adapter uses this form            |
-| `createRouteMapFromTree(tree, options?)` | Builds a `RouteMap` from a `RouteTree` that you extracted before                  |
-| `buildRouteTree(routes)`                 | Builds a `RouteTree` from an array of `RouteInfo` objects                         |
-| `machineToGraph(machine)`                | Converts a machine into a typed `@statelyai/graph` `Graph`, for a graph algorithm |
+| Export                                   | Description                                                             |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `buildRouteTree(routes)`                 | Builds a `RouteTree` from an array of `RouteInfo` objects               |
+| `createRouteMapFromTree(tree, options?)` | Builds a `RouteMap` from a `RouteTree` that you extracted before        |
+| `ROOT_NODE_ID`                           | The ID of the synthetic root node. A walk of a tree must skip that node |
+
+The MAIN entry point reads no state machine. The machine half is
+`@xmachines/play-router/xstate`, below.
 
 ### Route Matching
 
@@ -409,16 +398,32 @@ bridge.disconnect();
 | `findRouteById(tree, id)`     | Finds a `RouteNode` by its state ID                                                                           |
 | `findRouteByPath(tree, path)` | Finds a `RouteNode` by its URL path. It also matches a dynamic pattern                                        |
 
-### Query Utilities
+### The machine half — subpath `@xmachines/play-router/xstate`
+
+A route of XMachines is a fact about a STATE. This entry point reads that fact out of an
+XState v5 machine. The main entry point reads it never, so `xstate` is an OPTIONAL peer
+dependency of this package, and a bundler drops `@statelyai/graph` for a consumer that
+imports this entry point nowhere.
+
+```typescript
+import { createRouteMap, extractMachineRoutes } from "@xmachines/play-router/xstate";
+```
 
 | Export                                            | Description                                                                                     |
 | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `extractMachineRoutes(machine)`                   | Converts an XState machine into a `RouteTree` with the state ID ↔ path maps                     |
+| `createRouteMap(machine, options?)`               | Builds a `RouteMap` directly from a machine. An adapter uses this form                          |
+| `machineToGraph(machine)`                         | Converts a machine into a typed `@statelyai/graph` `Graph`, for a graph algorithm               |
 | `getRoutableRoutes(tree)`                         | Returns every routable `RouteNode` in one flat array                                            |
 | `getNavigableRoutes(tree, stateId)`               | Returns the child routes that a state can reach, through the hierarchy and through a transition |
 | `routeExists(tree, path)`                         | Tells you if the tree holds a path                                                              |
 | `getRouteMappings(tree, options?)`                | The `{ stateId, path }` entries for a route table of a host, with an optional prefix            |
 | `getTransitionReachableRoutes(graph, stateId)`    | Returns the route paths that a state can reach through an XState transition                     |
 | `isRouteReachable(graph, fromStateId, toStateId)` | Tells you if a transition path is present between two states                                    |
+| `MachineGraph`                                    | The typed `@statelyai/graph` Graph, with `MachineNodeData` and `MachineEdgeData`                |
+
+No framework router adapter re-exports `createRouteMap`. Each one names no state machine,
+so a consumer of an adapter imports the function from `@xmachines/play-router/xstate`.
 
 ### Router Bridge
 
@@ -474,7 +479,7 @@ own effects and nothing else.
 | `mountKey(basePath, params?)`                         | A key that changes when the mount changes, compared BY VALUE                                |
 | `isMountableBridge(bridge)`                           | The run-time probe for a bridge that can move its mount                                     |
 | `createRouterConnection(bridge)`                      | Wraps a live bridge in the callable `RouterConnection` that `connectRouter` returns         |
-| `RouterConnection`                                    | The callable handle: `disconnect()`, and the mount to read and to move                      |
+| `RouterConnection`                                    | The callable handle: `disconnect()`, the mount to read and to move, and a `Disposable`      |
 
 Nothing here imports a framework, so this package keeps no framework dependency —
 `tests/provider-factory-parity.test.ts` holds that. `TNode` is the only thing in the
@@ -490,43 +495,40 @@ props that a framework decides, which is why it is a type parameter.
 
 ### Key Types
 
-| Export                             | Description                                                                                                                        |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `RouterBridge`                     | The interface of the `connect()` and `disconnect()` lifecycle                                                                      |
-| `MountableRouterBridge`            | A `RouterBridge` whose mount can move — it adds `basePath` and `setBasePath()`                                                     |
-| `RouteTree`                        | The hierarchical tree, with `root`, `byStateId`, `byPath`, and an optional `graph`                                                 |
-| `RouteNode`                        | One node of the tree, with `id`, `path`, `fullPath`, `stateId`, `children`, and `parent`                                           |
-| `RouteInfo`                        | The flat route descriptor that comes from a state node                                                                             |
-| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                                                                        |
-| `RoutableActor`                    | The minimal actor interface that `RouterBridgeBase` requires: `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`           |
-| `PlayActor`                        | The complete actor interface that `PlayRouterProvider` uses. It extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
-| `RouteMapping`                     | The `{ stateId, path }` pair that builds a `RouteMap`                                                                              |
-| `RouteMapping as BaseRouteMapping` | The alias of `RouteMapping`, for compatibility with an earlier version                                                             |
-| `MachineGraph`                     | The typed `@statelyai/graph` Graph, with `MachineNodeData` and `MachineEdgeData`                                                   |
-| `WindowLike`                       | The minimal `window` interface that you can inject for SSR and for a test                                                          |
-| `LocationLike`                     | The minimal `location` interface that you can inject for SSR and for a test                                                        |
+| Export                  | Description                                                                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `RouterBridge`          | The interface of the `connect()` and `disconnect()` lifecycle                                                                            |
+| `MountableRouterBridge` | A `RouterBridge` whose mount can move — it adds `basePath` and `setBasePath()`                                                           |
+| `RouteTree`             | The hierarchical tree, with `root`, `byStateId`, `byPath`, and an optional `graph`                                                       |
+| `RouteNode`             | One node of the tree, with `id`, `path`, `fullPath`, `stateId`, `children`, and `parent`                                                 |
+| `RouteInfo`             | The flat route descriptor that comes from a state node                                                                                   |
+| `PlayRouteEvent`        | Routing event `{ type: "play.route", to, params?, query?, data? }`                                                                       |
+| `Routable`              | The optional routing capability of an actor: `currentRoute` and `initialRoute`                                                           |
+| `RoutableActor`         | The actor interface that `RouterBridgeBase` and `PlayRouterProvider` require: `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)` |
+| `RouteMapping`          | The `{ stateId, path }` pair that builds a `RouteMap`                                                                                    |
+| `RouteObject`           | The object form of `meta.route`: `path`, and the `handler`, `reenter` and `data` fields                                                  |
+| `RouteMetadata`         | The union of the two forms of `meta.route`: the path string, or a `RouteObject`                                                          |
+| `RouteData`             | The resolved extra data of a route, which reaches the machine as `context.data`                                                          |
+| `RouteDataResolver`     | The function form of `RouteObject.data`: `({ context, event }) => RouteData`                                                             |
+| `WindowLike`            | The minimal `window` interface that you can inject for SSR and for a test                                                                |
+| `LocationLike`          | The minimal `location` interface that you can inject for SSR and for a test                                                              |
 
 ### Errors (subpath `@xmachines/play-router/errors`)
 
-| Class                        | Code                                    | When thrown                                                                                                     |
-| ---------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` cannot send a `play.route` event                                                        |
-| `DuplicateBridgeError`       | `PLAY_ROUTER_DUPLICATE_BRIDGE`          | A second bridge tries to connect to an actor that already has one                                               |
-| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | The URLPattern API is absent, and no polyfill is loaded                                                         |
-| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern does not compile, or two of its params land on one URLPattern group                             |
-| `EmptyRoutePathError`        | `PLAY_ROUTE_EMPTY_PATH`                 | A state declares `meta.route: ""`                                                                               |
-| `InvalidStateIdError`        | `PLAY_ROUTE_INVALID_STATE_ID`           | A route names a state ID that the machine graph does not hold                                                   |
-| `DuplicateRoutePathError`    | `PLAY_ROUTE_DUPLICATE_PATH`             | Two or more states share the same URL path                                                                      |
-| `UnknownStateTypeError`      | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`         | A state node has an XState `.type` value that the package does not know                                         |
-| `InvalidBasePathError`       | `PLAY_ROUTER_INVALID_BASE_PATH`         | A `basePath` resolves to one concrete prefix never (`*`, `:p?`, `$p`, `?`, `#`, a scheme, `.`/`..`, whitespace) |
-| `MissingBasePathParamError`  | `PLAY_ROUTER_MISSING_BASE_PATH_PARAM`   | A `:param` of a `basePath` has no value in `basePathParams`                                                     |
+| Class                       | Code                                  | When thrown                                                                                                     |
+| --------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `RouterSyncError`           | `PLAY_ROUTER_SYNC_FAILED`             | `syncActorFromRouter()` cannot send a `play.route` event                                                        |
+| `DuplicateBridgeError`      | `PLAY_ROUTER_DUPLICATE_BRIDGE`        | A second bridge tries to connect to an actor that already has one                                               |
+| `InvalidRoutePatternError`  | `PLAY_ROUTE_MAP_INVALID_PATTERN`      | A route pattern does not compile, or two of its params land on one URLPattern group                             |
+| `EmptyRoutePathError`       | `PLAY_ROUTE_EMPTY_PATH`               | A state declares `meta.route: ""`                                                                               |
+| `InvalidStateIdError`       | `PLAY_ROUTE_INVALID_STATE_ID`         | A route names a state ID that the machine graph does not hold                                                   |
+| `DuplicateRoutePathError`   | `PLAY_ROUTE_DUPLICATE_PATH`           | Two or more states share the same URL path                                                                      |
+| `UnknownStateTypeError`     | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`       | A state node has an XState `.type` value that the package does not know                                         |
+| `InvalidBasePathError`      | `PLAY_ROUTER_INVALID_BASE_PATH`       | A `basePath` resolves to one concrete prefix never (`*`, `:p?`, `$p`, `?`, `#`, a scheme, `.`/`..`, whitespace) |
+| `MissingBasePathParamError` | `PLAY_ROUTER_MISSING_BASE_PATH_PARAM` | A `:param` of a `basePath` has no value in `basePathParams`                                                     |
 
 ```typescript
-import {
-	RouterSyncError,
-	DuplicateBridgeError,
-	URLPatternUnavailableError,
-} from "@xmachines/play-router/errors";
+import { RouterSyncError, DuplicateBridgeError } from "@xmachines/play-router/errors";
 
 // bridge from the adapter example above
 try {
@@ -567,6 +569,28 @@ states: {
 }
 ```
 
+### The object form
+
+The object form carries the path and any metadata of your own, such as a title or a
+breadcrumb. It also carries three fields that the routing layer reads:
+
+| Field     | Default  | What it does                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------- |
+| `path`    | required | The template of the route path                                                  |
+| `handler` | `"root"` | Where the generated `play.route` transition sits: `"root"`, `"local"`, `"both"` |
+| `reenter` | `false`  | Whether the transition re-enters its own domain. See the note below.            |
+| `data`    | none     | The extra data of the route: a literal value, or a function of the event        |
+
+`@xmachines/play-xstate` reads `handler`, `reenter`, and `data` when it generates the
+transitions. See the README of that package for what each value does.
+
+**The four names are RESERVED, and this is a change of behaviour.** An earlier release
+read `path` alone, so a state could put any name of its own beside it. A state that
+carries its own `handler` value now throws an `InvalidRouteHandlerError` at the format
+time, and the machine builds never; a state that carries its own `data` value now writes
+that value to `context.data`, where the `/context` projection of every view reads it.
+Give such a field another name.
+
 ### Relative vs absolute paths
 
 A child route that starts with `/` is absolute, and it does not inherit the path of its parent. A child route without the first `/` is relative to its nearest routable ancestor:
@@ -592,47 +616,17 @@ states: {
 
 Always use `node.fullPath` to match a browser URL and to build a route map. Never use `node.path` for this.
 
-## Testing
-
-```bash
-# Run tests for this package
-pnpm --filter @xmachines/play-router test
-
-# Watch mode
-pnpm --filter @xmachines/play-router run test:watch
-```
-
-`@xmachines/play-router-shared` holds a contract test suite of the router bridge, for the
-author of an adapter. That suite drives a real actor. Therefore it is one layer above this
-package, and `@xmachines/play-router` keeps no dependency on an actor runtime.
-`@xmachines/play-router-shared` is a private workspace package. Thus only an adapter author
-in this repository can use the suite:
-
-```typescript
-import { runBridgeContractTests } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
-
-runBridgeContractTests({
-	name: "MyRouterBridge",
-	createHarness(initialPath) {
-		// return ContractHarness with bridge, actor, simulateNavigation, getLastNavigatedPath
-	},
-	createRestoredHarness(routedPath) {
-		// return ContractHarness whose actor is restored to routedPath
-		// while the mock router starts at the machine's initial route
-	},
-});
-```
-
 ## Related Packages
 
 - **[@xmachines/play](../play/README.md)** — Core protocol types (`PlayEvent`, `PlayError`)
-- **[@xmachines/play-actor](../play-actor/README.md)** — the abstract actor base class (`AbstractActor`, `Routable`). Every `AbstractActor` subclass satisfies `RoutableActor` structurally
+- **[@xmachines/play-actor](../play-actor/README.md)** — the actor contract (`PlayActor`). An actor that adds `Routable` of this package satisfies `RoutableActor` structurally
+- **[@xmachines/play-url](../play-url/README.md)** — the URL language. This package re-exports its base path and its framework params, for an adapter on `RouterBridgeBase`
 - **[@xmachines/play-signals](../play-signals/README.md)** — the TC39 Signals polyfill that observes the actor route
 - **[@xmachines/play-xstate](../play-xstate/README.md)** — the XState v5 logic adapter, which works with a route tree
 - **[@xmachines/play-tanstack-router](../play-tanstack-router/README.md)** — Shared TanStack Router bridge base (framework-agnostic)
 - **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** — TanStack Router adapter (React)
 - **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md)** — TanStack Router adapter (SolidJS)
-- **[@xmachines/play-react-router](../play-react-router/README.md)** — React Router v7 adapter
+- **[@xmachines/play-react-router](../play-react-router/README.md)** — React Router 7/8 adapter
 - **[@xmachines/play-vue-router](../play-vue-router/README.md)** — Vue Router adapter
 - **[@xmachines/play-solid-router](../play-solid-router/README.md)** — SolidJS Router adapter
 
@@ -640,83 +634,8 @@ runBridgeContractTests({
 
 MIT — see [LICENSE](LICENSE).
 
-## Classes
-
-- [RouteMap](classes/RouteMap.md)
-- [RouterBridgeBase](classes/RouterBridgeBase.md)
-
-## Interfaces
-
-- [BasePathOptions](interfaces/BasePathOptions.md)
-- [BuildPlayRouteEventOptions](interfaces/BuildPlayRouteEventOptions.md)
-- [FrameworkParamsSource](interfaces/FrameworkParamsSource.md)
-- [LocationLike](interfaces/LocationLike.md)
-- [MachineEdgeData](interfaces/MachineEdgeData.md)
-- [MachineNodeData](interfaces/MachineNodeData.md)
-- [MountableRouterBridge](interfaces/MountableRouterBridge.md)
-- [OpenProviderBridgeArgs](interfaces/OpenProviderBridgeArgs.md)
-- [PlayActor](interfaces/PlayActor.md)
-- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
-- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
-- [ResolvedBasePath](interfaces/ResolvedBasePath.md)
-- [ResolvedRoutePath](interfaces/ResolvedRoutePath.md)
-- [RoutableActor](interfaces/RoutableActor.md)
-- [RouteInfo](interfaces/RouteInfo.md)
-- [RouteMapOptions](interfaces/RouteMapOptions.md)
-- [RouteMapping](interfaces/RouteMapping.md)
-- [RouteMatch](interfaces/RouteMatch.md)
-- [RouteNode](interfaces/RouteNode.md)
-- [RouteObject](interfaces/RouteObject.md)
-- [RouterBridge](interfaces/RouterBridge.md)
-- [RouterConnection](interfaces/RouterConnection.md)
-- [RouteTree](interfaces/RouteTree.md)
-- [RouteWatcherHandle](interfaces/RouteWatcherHandle.md)
-- [WindowLike](interfaces/WindowLike.md)
-
-## Type Aliases
-
-- [~~BaseRouteMapping~~](type-aliases/BaseRouteMapping.md)
-- [MachineGraph](type-aliases/MachineGraph.md)
-- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
-- [RouteMetadata](type-aliases/RouteMetadata.md)
-
-## Variables
-
-- [NO\_BASE\_PATH](variables/NO_BASE_PATH.md)
-
-## Functions
-
-- [buildPlayRouteEvent](functions/buildPlayRouteEvent.md)
-- [buildRouteTree](functions/buildRouteTree.md)
-- [cleanFrameworkParams](functions/cleanFrameworkParams.md)
-- [createRouteMap](functions/createRouteMap.md)
-- [createRouteMapFromTree](functions/createRouteMapFromTree.md)
-- [createRouterConnection](functions/createRouterConnection.md)
-- [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
-- [extractMachineRoutes](functions/extractMachineRoutes.md)
-- [extractQuery](functions/extractQuery.md)
-- [extractRouteParams](functions/extractRouteParams.md)
-- [findRouteById](functions/findRouteById.md)
-- [findRouteByPath](functions/findRouteByPath.md)
-- [getNavigableRoutes](functions/getNavigableRoutes.md)
-- [getPatternParamNames](functions/getPatternParamNames.md)
-- [getRequiredPatternParamNames](functions/getRequiredPatternParamNames.md)
-- [getRoutableRoutes](functions/getRoutableRoutes.md)
-- [getRouteMappings](functions/getRouteMappings.md)
-- [getTransitionReachableRoutes](functions/getTransitionReachableRoutes.md)
-- [isMountableBridge](functions/isMountableBridge.md)
-- [isRouteReachable](functions/isRouteReachable.md)
-- [joinBasePath](functions/joinBasePath.md)
-- [machineToGraph](functions/machineToGraph.md)
-- [mountKey](functions/mountKey.md)
-- [normalizeBasePath](functions/normalizeBasePath.md)
-- [openProviderBridge](functions/openProviderBridge.md)
-- [pickOwnParams](functions/pickOwnParams.md)
-- [repointProviderBridge](functions/repointProviderBridge.md)
-- [resolveBasePath](functions/resolveBasePath.md)
-- [resolveFrameworkParams](functions/resolveFrameworkParams.md)
-- [routeExists](functions/routeExists.md)
-- [sanitizePathname](functions/sanitizePathname.md)
-- [stripBasePath](functions/stripBasePath.md)
-- [validateRouteFormat](functions/validateRouteFormat.md)
-- [validateStateExists](functions/validateStateExists.md)
+## Modules
+
+- [errors](errors/README.md)
+- [index](index/README.md)
+- [xstate](xstate/README.md)

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

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / errors
+
+# errors
+
+## Classes
+
+- [DuplicateBridgeError](classes/DuplicateBridgeError.md)
+- [DuplicateRoutePathError](classes/DuplicateRoutePathError.md)
+- [EmptyRoutePathError](classes/EmptyRoutePathError.md)
+- [InvalidBasePathError](classes/InvalidBasePathError.md)
+- [InvalidRoutePatternError](classes/InvalidRoutePatternError.md)
+- [InvalidStateIdError](classes/InvalidStateIdError.md)
+- [MissingBasePathParamError](classes/MissingBasePathParamError.md)
+- [RouterSyncError](classes/RouterSyncError.md)
+- [UnknownStateTypeError](classes/UnknownStateTypeError.md)

package/api/@xmachines/play-router/errors/classes/DuplicateBridgeError.md

@@ -0,0 +1,191 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [errors](../README.md) / DuplicateBridgeError
+
+# Class: DuplicateBridgeError
+
+Defined in: [packages/play-router/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/errors.ts#L75)
+
+`RouterBridgeBase.connect()` throws this error when a second bridge connects to an
+actor with an active bridge connection.
+
+One actor can hold one router bridge at a time. Two bridges of the same actor both
+receive and process every navigation event of the router. They therefore send two
+`play.route` events to the actor, and their `lastSyncedPath` values of the echo
+suppression contradict each other.
+
+**The remedy:** call `bridge.disconnect()` on the first bridge before you connect
+the second one. You can also permit one active `connectRouter()` call for each
+actor at a time.
+
+**Error code:** `PLAY_ROUTER_DUPLICATE_BRIDGE`
+
+## Example
+
+```typescript
+import { DuplicateBridgeError } from "@xmachines/play-router/errors";
+
+try {
+	bridge.connect();
+} catch (err) {
+	if (err instanceof DuplicateBridgeError) {
+		console.error("Actor already has an active router bridge — disconnect first.");
+	}
+}
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new DuplicateBridgeError(): DuplicateBridgeError;
+```
+
+Defined in: [packages/play-router/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/errors.ts#L76)
+
+#### Returns
+
+`DuplicateBridgeError`
+
+#### 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-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)