@xmachines/docs 2.0.0 → 2.1.0

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

@@ -4,11 +4,9 @@
 
 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.0.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-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-router)
 
-Graph-based route extraction and bidirectional lookup enabling Actor Authority over navigation.
-
-Part of the [xmachines-js monorepo](../../README.md).
+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.
 
 ## Installation
 
@@ -23,9 +21,9 @@ pnpm add @xmachines/play-router
 
 **URLPattern polyfill (Node.js < 24 / older browsers):**
 
-`@xmachines/play-router` uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for dynamic route matching. URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+).
+`@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+).
 
-On environments without native support, load a polyfill **before** importing this package:
+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
@@ -38,7 +36,7 @@ Install the polyfill:
 pnpm add urlpattern-polyfill
 ```
 
-`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — consumers must install and load it when their runtime lacks native URLPattern support.
+`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.
 
 ## Usage
 
@@ -97,8 +95,13 @@ routeMap.getPathByStateId("profile"); // "/profile/:userId"
 ### Sending `play.route` events
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
+// machine: your routable machine (states carry meta.route)
+const actor = definePlayer({ machine })();
+actor.start();
+
 // Navigate to a state by ID
 const event: PlayRouteEvent = {
 	type: "play.route",
@@ -122,14 +125,21 @@ actor.send({
 });
 ```
 
-### Implementing a `RouterBridgeBase` adapter
+### How to write a `RouterBridgeBase` adapter
 
-Extend `RouterBridgeBase` and implement the three abstract methods for your framework:
+Extend `RouterBridgeBase`, then implement the three abstract methods for your framework:
 
 ```typescript
-import { RouterBridgeBase } from "@xmachines/play-router";
+import { RouterBridgeBase, createRouteMap } from "@xmachines/play-router";
 import type { RoutableActor } from "@xmachines/play-router";
 
+// Shape of your framework's router — adjust to its real API
+type MyRouter = {
+	navigate(path: string): void;
+	subscribe(handler: (location: { pathname: string; search: string }) => void): () => void;
+	state: { location: { pathname: string } };
+};
+
 export class MyRouterBridge extends RouterBridgeBase {
 	private unsubscribe: (() => void) | null = null;
 
@@ -165,7 +175,8 @@ export class MyRouterBridge extends RouterBridgeBase {
 	}
 }
 
-// Usage
+// Usage — myRouter: your framework's router instance;
+// machine/actor: your routable machine and its started actor
 const routeMap = createRouteMap(machine);
 const bridge = new MyRouterBridge(myRouter, actor, routeMap);
 bridge.connect();
@@ -177,79 +188,79 @@ bridge.disconnect();
 
 ### Route Extraction
 
-| Export                                   | Description                                                                        |
-| ---------------------------------------- | ---------------------------------------------------------------------------------- |
-| `extractMachineRoutes(machine)`          | Convert an XState machine to a `RouteTree` with bidirectional state ID ↔ path maps |
-| `createRouteMap(machine, options?)`      | Build a `RouteMap` directly from a machine (preferred form for adapters)           |
-| `createRouteMapFromTree(tree, options?)` | Build a `RouteMap` from an already-extracted `RouteTree`                           |
-| `buildRouteTree(routes)`                 | Build a `RouteTree` from an array of `RouteInfo` objects                           |
-| `machineToGraph(machine)`                | Convert a machine to a typed `@statelyai/graph` `Graph` for graph algorithm access |
+| 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 |
 
 ### Route Matching
 
-| Export                        | Description                                                                                |
-| ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `RouteMap`                    | Bidirectional `stateId ↔ path` lookup class; supports O(1) exact and O(k) pattern matching |
-| `findRouteById(tree, id)`     | Look up a `RouteNode` by state ID                                                          |
-| `findRouteByPath(tree, path)` | Look up a `RouteNode` by URL path (supports dynamic patterns)                              |
+| Export                        | Description                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `RouteMap`                    | The `stateId ↔ path` lookup class for both directions. It matches an exact path in O(1) and a pattern in O(k) |
+| `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
 
-| Export                                            | Description                                                               |
-| ------------------------------------------------- | ------------------------------------------------------------------------- |
-| `getRoutableRoutes(tree)`                         | All routable `RouteNode`s as a flat array                                 |
-| `getNavigableRoutes(tree, stateId)`               | Child routes reachable from a state (hierarchical + transition-reachable) |
-| `routeExists(tree, path)`                         | Check whether a path is registered in the tree                            |
-| `getTransitionReachableRoutes(graph, stateId)`    | Route paths reachable via XState transitions from a state                 |
-| `isRouteReachable(graph, fromStateId, toStateId)` | Check whether a transition path exists between two states                 |
+| Export                                            | Description                                                                                     |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `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                                                              |
+| `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                                    |
 
 ### Router Bridge
 
-| Export                                  | Description                                                                           |
-| --------------------------------------- | ------------------------------------------------------------------------------------- |
-| `RouterBridgeBase`                      | Abstract base class for framework router adapters; implements `RouterBridge` protocol |
-| `sanitizePathname(path)`                | Normalize a raw pathname; returns `null` for paths > 2048 chars or malformed input    |
-| `buildPlayRouteEvent(options)`          | Build a `PlayRouteEvent` from a pathname + route-map match result                     |
-| `extractRouteParams(pathname, pattern)` | Extract path parameters from a URL using URLPattern                                   |
-| `extractQuery(search)`                  | Extract query parameters from a URL search string                                     |
+| Export                                  | Description                                                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `RouterBridgeBase`                      | The abstract base class of each framework router adapter. It implements the `RouterBridge` protocol           |
+| `sanitizePathname(path)`                | Normalizes a raw pathname. It returns `null` for a path of more than 2048 characters, and for malformed input |
+| `buildPlayRouteEvent(options)`          | Builds a `PlayRouteEvent` from a pathname and a route-map match result                                        |
+| `extractRouteParams(pathname, pattern)` | Reads the path parameters of a URL with URLPattern                                                            |
+| `extractQuery(search)`                  | Reads the query parameters of a URL search string                                                             |
 
 ### Validation
 
-| Export                                   | Description                                           |
-| ---------------------------------------- | ----------------------------------------------------- |
-| `validateRouteFormat(route, stateId)`    | Assert route path is non-empty                        |
-| `validateStateExists(stateId, stateIds)` | Assert a state ID is present in the machine graph     |
-| `detectDuplicateRoutes(routes)`          | Throw if any two states resolve to the same full path |
+| Export                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `validateRouteFormat(route, stateId)`    | Asserts that the route path is not empty             |
+| `validateStateExists(stateId, stateIds)` | Asserts that the machine graph holds the state ID    |
+| `detectDuplicateRoutes(routes)`          | Throws when two states resolve to the same full path |
 
 ### Key Types
 
-| Export                             | Description                                                                                                            |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `RouterBridge`                     | Interface for `connect()` / `disconnect()` lifecycle                                                                   |
-| `RouteTree`                        | Hierarchical tree with `root`, `byStateId`, `byPath`, and optional `graph`                                             |
-| `RouteNode`                        | Single node in the tree with `id`, `path`, `fullPath`, `stateId`, `children`, `parent`                                 |
-| `RouteInfo`                        | Flat route descriptor extracted from a state node                                                                      |
-| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                                                            |
-| `RoutableActor`                    | Minimal actor interface required by `RouterBridgeBase` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`    |
-| `PlayActor`                        | Full actor interface used by `PlayRouterProvider` — extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
-| `RouteMapping`                     | `{ stateId, path }` pair used to build a `RouteMap`                                                                    |
-| `RouteMapping as BaseRouteMapping` | Alias for `RouteMapping` (backwards-compat re-export)                                                                  |
-| `MachineGraph`                     | Typed `@statelyai/graph` Graph with `MachineNodeData` / `MachineEdgeData`                                              |
-| `WindowLike`                       | Injectable minimal `window` interface for SSR / testing                                                                |
-| `LocationLike`                     | Injectable minimal `location` interface for SSR / testing                                                              |
+| Export                             | Description                                                                                                                        |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `RouterBridge`                     | The interface of the `connect()` and `disconnect()` lifecycle                                                                      |
+| `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                                                        |
 
 ### Errors (subpath `@xmachines/play-router/errors`)
 
-| Class                        | Code                                    | When thrown                                                       |
-| ---------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
-| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` fails to 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` | URLPattern API is absent and no polyfill is loaded                |
-| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern string is rejected by the URLPattern constructor  |
-| `EmptyRoutePathError`        | `PLAY_ROUTE_EMPTY_PATH`                 | A state declares `meta.route: ""`                                 |
-| `InvalidStateIdError`        | `PLAY_ROUTE_INVALID_STATE_ID`           | A route references a state ID not in the machine graph            |
-| `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 unrecognised XState `.type` value             |
+| 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`        | The URLPattern constructor refuses a route pattern string               |
+| `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 |
 
 ```typescript
 import {
@@ -258,6 +269,7 @@ import {
 	URLPatternUnavailableError,
 } from "@xmachines/play-router/errors";
 
+// bridge from the adapter example above
 try {
 	bridge.connect();
 } catch (err) {
@@ -273,7 +285,7 @@ try {
 
 ### `meta.route` patterns
 
-Routes are declared on XState state nodes via the `meta.route` field:
+Declare the route of an XState state node in its `meta.route` field:
 
 ```typescript
 states: {
@@ -298,7 +310,7 @@ states: {
 
 ### Relative vs absolute paths
 
-Child routes with a leading `/` are absolute (do not inherit the parent path). Without a leading `/`, they resolve relative to their nearest routable ancestor:
+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:
 
 ```typescript
 states: {
@@ -319,7 +331,7 @@ states: {
 }
 ```
 
-Always use `node.fullPath` (never `node.path`) for browser URL matching and route map construction.
+Always use `node.fullPath` to match a browser URL and to build a route map. Never use `node.path` for this.
 
 ## Testing
 
@@ -331,10 +343,11 @@ pnpm --filter @xmachines/play-router test
 pnpm --filter @xmachines/play-router run test:watch
 ```
 
-A router bridge contract test suite for adapter authors lives in
-`@xmachines/play-router-shared` (it drives a real actor, so it sits one layer
-above this package to keep `@xmachines/play-router` free of an actor-runtime
-dependency):
+`@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";
@@ -344,15 +357,19 @@ runBridgeContractTests({
 	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)** — Abstract actor base class (`AbstractActor`, `Routable`); all `AbstractActor` subclasses satisfy `RoutableActor` structurally
-- **[@xmachines/play-signals](../play-signals/README.md)** — TC39 Signals polyfill used for actor route observation
-- **[@xmachines/play-xstate](../play-xstate/README.md)** — XState v5 logic adapter that integrates with route trees
+- **[@xmachines/play-actor](../play-actor/README.md)** — the abstract actor base class (`AbstractActor`, `Routable`). Every `AbstractActor` subclass satisfies `RoutableActor` structurally
+- **[@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)
@@ -392,6 +409,7 @@ MIT — see [LICENSE](LICENSE).
 
 ## Type Aliases
 
+- [~~BaseRouteMapping~~](type-aliases/BaseRouteMapping.md)
 - [MachineGraph](type-aliases/MachineGraph.md)
 - [RouteMetadata](type-aliases/RouteMetadata.md)
 
@@ -416,9 +434,3 @@ MIT — see [LICENSE](LICENSE).
 - [sanitizePathname](functions/sanitizePathname.md)
 - [validateRouteFormat](functions/validateRouteFormat.md)
 - [validateStateExists](functions/validateStateExists.md)
-
-## References
-
-### BaseRouteMapping
-
-Renames and re-exports [RouteMapping](interfaces/RouteMapping.md)

package/api/@xmachines/play-router/classes/RouteMap.md

@@ -2,32 +2,33 @@
 
 # Class: RouteMap
 
-Defined in: [base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L105)
 
-Shared bidirectional route map base class.
+The shared base class of the route map for both directions.
 
-All framework adapters use this class as their route map — they add no logic of their
-own and inherit the full public API from here.
+Every framework adapter uses this class as its route map. An adapter adds no logic
+of its own, and it inherits the complete public API from here.
 
-**Lookup strategy:**
+**The strategy of a lookup:**
 
-- Static paths (no `:param`) → O(1) `Map` lookup
-- Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
-  of routes sharing the same first path segment
-- Results are cached after the first match in an LRU cache (default 500 entries,
-  configurable via the `cacheSize` constructor option)
+- A static path, without a `:param` → a `Map` lookup in O(1)
+- A dynamic path → a scan of the bucket index in O(k), with `URLPattern`, where
+  `k` is the number of the routes with the same first path segment
+- The class keeps each result of a first match in an LRU cache. The default size
+  is 500 entries, and the `cacheSize` constructor option changes it
 
-**Pattern syntax** (`:param` / `:param?` / `*`):
+**The syntax of a pattern** (`:param`, `:param?`, and `*`):
 
-- `:param` — required segment, matches exactly one non-`/` segment
-- `:param?` — optional segment, matches zero or one non-`/` segment
-- `*` — wildcard, matches any number of segments (URLPattern semantics)
+- `:param` — a necessary segment. It matches exactly one segment without a `/`
+- `:param?` — an optional segment. It matches zero segments or one segment without a `/`
+- `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
-**StateId forms:** stateIds may be registered and looked up in either
-`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
-`getStateIdByPath` returns the stateId exactly as registered;
-`getPathByStateId` accepts both forms. Registering the same stateId in both
-forms refers to one entry (the later registration wins for reverse lookup).
+**The forms of a stateId:** you can register a stateId, and you can look one up,
+in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
+canonical form itself. `getStateIdByPath` returns the stateId exactly as you
+registered it, and `getPathByStateId` accepts both forms. A registration of the
+same stateId in both forms gives one entry, and the later registration wins for
+the lookup in the other direction.
 
 ## Example
 
@@ -57,21 +58,22 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L127)
+Defined in: [base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L133)
 
-Build a route map from an array of state ID ↔ path mappings.
+Builds a route map from an array of the mappings between a state ID and a path.
 
-Static paths (no `:param`) are indexed in an O(1) `Map`.
-Parameterized paths are compiled to `URLPattern` and grouped into first-segment
-buckets for efficient candidate selection.
+The constructor puts each static path, which holds no `:param`, into a `Map` for a
+lookup in O(1). It compiles each parameterized path to a `URLPattern`, and it
+groups the patterns into the buckets of the first segment. The selection of the
+candidates is therefore efficient.
 
 #### Parameters
 
-| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
-| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
-| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
-| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                                                                                                                                                                                                                                                                                                                                                     |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | The optional configuration. `options.cacheSize`: the maximum number of the resolved parameterized path lookups in the cache. The default is `500`. Raise it for an application with many different values in a parameterized URL, for example a page of a user profile with thousands of different IDs. After an eviction, the path goes to the bucket pattern scan in O(k) again, which is correct but slower. The smallest effective value is `1`, because QuickLRU requires it. |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 #### Returns
 
@@ -85,31 +87,31 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [base-route-map.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L225)
 
-Look up the path pattern registered for a state ID.
+Returns the path pattern of a state ID.
 
-Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
-which form was used at registration — lookups are canonicalized internally,
-so consumers never need to try both forms.
+The method accepts the stateId in the form `"#stateId"` and in the form
+`"stateId"`, and the form of the registration has no effect. The method makes the
+canonical form itself. Therefore a consumer tries never both forms.
 
 #### Parameters
 
-| Parameter | Type     | Description                                               |
-| --------- | -------- | --------------------------------------------------------- |
-| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+| Parameter | Type     | Description                                                                 |
+| --------- | -------- | --------------------------------------------------------------------------- |
+| `stateId` | `string` | The state ID of the state machine, for example `"profile"` or `"#settings"` |
 
 #### Returns
 
 `string` \| `null`
 
-The registered path pattern, or `null` if the state ID is unknown
+The registered path pattern, or `null` when the state ID is unknown
 
 #### Example
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
+map.getPathByStateId("#profile"); // "/profile/:userId" — the same entry
 map.getPathByStateId("missing"); // null
 ```
 
@@ -121,25 +123,25 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [base-route-map.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L185)
 
-Resolve a URL path to its mapped state ID.
+Resolves a URL path to its state ID.
 
-Strips query strings and hash fragments before matching. Tries an O(1) exact
-lookup first, then falls back to bucket-indexed pattern matching. Results are
-cached after the first pattern match.
+The method removes the query string and the hash fragment before the match. It
+tries an exact lookup in O(1) first, then it uses the pattern match on the bucket
+index. It keeps each result of a first pattern match in the cache.
 
 #### Parameters
 
-| Parameter | Type     | Description                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------ |
-| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+| Parameter | Type     | Description                                                                            |
+| --------- | -------- | -------------------------------------------------------------------------------------- |
+| `path`    | `string` | The URL pathname. It can hold a query and a hash, for example `"/profile/123?ref=nav"` |
 
 #### Returns
 
 `string` \| `null`
 
-The mapped state ID, or `null` if no route matches
+The state ID of the path, or `null` when no route matches
 
 #### Example
 

package/api/@xmachines/play-router/classes/RouterBridgeBase.md

@@ -2,19 +2,22 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L96)
+Defined in: [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L99)
 
-Abstract base class for all `@xmachines` router adapter bridges.
+The abstract base class of every router adapter bridge of `@xmachines`.
 
-Implements RouterBridge protocol and contains all common bridge logic.
-Subclasses only need to implement the 3 abstract methods that differ
-between frameworks.
+The class implements the RouterBridge protocol, and it holds every part of the
+bridge logic that the adapters share. A subclass implements the 3 abstract methods
+that are different in each framework, and it implements nothing more.
 
 ## Extended by
 
+- [`DomRouterBridge`](../../play-dom-router/classes/DomRouterBridge.md)
 - [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
 - [`TanStackRouterBridgeBase`](../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
 - [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
+- [`SvelteKitRouterBridge`](../../play-sveltekit-router/classes/SvelteKitRouterBridge.md)
+- [`SvelteSpaRouterBridge`](../../play-svelte-spa-router/classes/SvelteSpaRouterBridge.md)
 - [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
 - [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
 
@@ -30,14 +33,14 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L123)
+Defined in: [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L127)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                        |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. `getPathByStateId` may be keyed on either the `"#stateId"` or the bare `"stateId"` form — both forms are tried automatically by the bridge, so custom implementations (e.g. plain test objects) need only handle one. |
+| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | The route map of both directions, for the resolution between a `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A framework adapter usually wraps the result of `createRouteMap(machine)`, or an equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the bare form `"stateId"`. The bridge tries both forms. Therefore an implementation of your own, for example a plain test object, handles one form only. |
 | `routeMap.getPathByStateId` | -                                                                                                                   |
 | `routeMap.getStateIdByPath` | -                                                                                                                   |
 
@@ -53,21 +56,23 @@ Defined in: [router-bridge-base.ts:123](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L151)
+Defined in: [router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L158)
 
-Connect the router bridge to the Actor.
+Connects the router bridge to the Actor.
 
-Sets up the TC39 Signal watcher for actor → router direction and
-starts watching router changes (framework-specific).
+The method installs the TC39 Signal watcher of the direction from the actor to the
+router. It then starts the watch of the router changes, which each framework does
+in its own way.
 
-Ordering here is part of the bridge contract:
+The order of these steps is part of the contract of the bridge:
 
-- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
-- the actor watcher is installed before adapter router subscriptions
-- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The method installs the actor watcher before the router subscriptions of the adapter
+- The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
 
-Adapters that need custom initial-sync behavior should override
-`getInitialRouterPath()` rather than reordering `connect()` steps.
+An adapter that needs a different behavior of the first synchronization overrides
+`getInitialRouterPath()`. It does not change the order of the steps of
+`connect()`.
 
 #### Returns
 
@@ -85,11 +90,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/router-bridge-base.ts#L256)
+Defined in: [router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L270)
 
-Disconnect the router bridge from the Actor.
+Disconnects the router bridge from the Actor.
 
-Stops signal watching and unregisters framework-specific router listener.
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
 
 #### Returns