@xmachines/play-router 2.0.0-alpha.1 → 2.1.0

package/README.md

@@ -1,29 +1,27 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-router
 
-Route tree extraction from XState v6 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
+Route tree extraction from XState v5 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
-Graph-based route extraction and bidirectional lookup enabling Actor Authority over navigation.
+[![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)
 
-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
 
 ```bash
-pnpm add xstate@^6.0.0-alpha.19
+pnpm add xstate@^5.31.0
 pnpm add @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^6.0.0-alpha.19 — XState v6 state machine runtime
+- `xstate` ^5.31.0 — XState v5 state machine runtime
 
 **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
@@ -36,23 +34,17 @@ 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
 
 ### Extract routes from a machine
 
 ```typescript
-import { setup, types } from "xstate";
+import { createMachine } from "xstate";
 import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
 
-// meta.route on state nodes needs a declared meta schema —
-// without it, XState v6 types `meta` as `never`.
-const machine = setup({
-	schemas: {
-		meta: types<{ route?: string }>(),
-	},
-}).createMachine({
+const machine = createMachine({
 	id: "app",
 	initial: "home",
 	states: {
@@ -101,8 +93,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",
@@ -126,14 +123,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;
 
@@ -169,7 +173,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();
@@ -181,81 +186,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 |
-
-> **Graph shape under XState v6:** machines wired by `formatPlayRouteTransitions` expose their route navigation as statically-targeted `xstate.route` edges (one per routed state) plus a single dynamic `play.route` forwarder edge — tooling that previously filtered for per-route `play.route` edges should query `xstate.route` instead. Edge data marks guard presence with `guarded: true`; guard _names_ are unrecoverable under v6 (`guardType` is never populated).
+| 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 {
@@ -264,6 +267,7 @@ import {
 	URLPatternUnavailableError,
 } from "@xmachines/play-router/errors";
 
+// bridge from the adapter example above
 try {
 	bridge.connect();
 } catch (err) {
@@ -279,7 +283,7 @@ try {
 
 ### `meta.route` patterns
 
-Routes are declared on XState state nodes via the `meta.route` field. The machine's `setup({ schemas })` must declare a matching `meta` schema (e.g. `meta: types<{ route?: string | { path: string; title?: string } }>()`) — without one, XState v6 types state `meta` as `never`:
+Declare the route of an XState state node in its `meta.route` field:
 
 ```typescript
 states: {
@@ -304,7 +308,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: {
@@ -325,7 +329,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
 
@@ -337,10 +341,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";
@@ -350,15 +355,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 v6 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)

package/dist/base-route-map.d.ts

@@ -1,20 +1,23 @@
 /**
- * RouteMap — Shared bidirectional route mapping base class
+ * RouteMap — the shared base class of the route map for both directions
  *
- * Provides bucket-based pattern matching shared across all framework adapters.
- * Adapters extend this class rather than duplicating the pattern-match logic.
+ * The class gives you the pattern match on buckets, and every framework adapter
+ * uses it. An adapter extends this class, and it therefore holds no copy of the
+ * pattern match logic.
  *
- * Algorithm: O(1) exact match via Map, then bucket-based O(k) pattern match
- * where k = routes in the first-segment bucket (typically << total routes).
- * Uses URLPattern for parameterized route matching.
+ * The algorithm: an exact match in O(1) through a Map, then a pattern match on the
+ * buckets in O(k), where k is the number of the routes in the bucket of the first
+ * segment, and that number is much smaller than the number of all the routes. The
+ * class matches a parameterized route with URLPattern.
  */
 /**
- * A single state ID ↔ path mapping entry.
+ * One entry of the map between a state ID and a path.
  *
- * Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
- * Adapter packages re-export a structurally compatible `RouteMapping` type under
- * their own name. This type is published from `@xmachines/play-router` as
- * `RouteMapping` to avoid name collisions with those adapter-local types.
+ * Both fields are `readonly`, because a mapping is immutable after the caller gives
+ * it to `RouteMap`. An adapter package re-exports a structurally compatible
+ * `RouteMapping` type under its own name. `@xmachines/play-router` publishes this
+ * type as `RouteMapping`, and its name therefore does not collide with such a local
+ * type of an adapter.
  *
  * @example
  * ```typescript
@@ -24,34 +27,35 @@
  * ```
  */
 export interface RouteMapping {
-    /** State machine state ID (e.g., `"home"`, `"#profile"`) */
+    /** The state ID of the state machine, for example `"home"` or `"#profile"` */
     readonly stateId: string;
-    /** URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) */
+    /** The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` */
     readonly path: string;
 }
 /**
- * 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:**
- * - 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)
+ * **The strategy of a lookup:**
+ * - 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?` / `*`):
- * - `: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)
+ * **The syntax of a pattern** (`:param`, `:param?`, and `*`):
+ * - `: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
  * ```typescript
@@ -73,39 +77,41 @@ export interface RouteMapping {
  * ```
  */
 export declare class RouteMap {
-    /** Keyed on the canonical (bare, `#`-stripped) stateId form. */
+    /** The key is the canonical stateId form, which is bare and without a `#`. */
     private stateIdToPath;
     private pathToStateId;
     private patternBuckets;
     private pathMatchCache;
     /**
-     * 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.
      *
-     * @param mappings - Array of `{ stateId, path }` entries. Order determines
-     *   priority when multiple patterns could match the same path.
-     * @param options - 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).
+     * @param mappings - The array of the `{ stateId, path }` entries. The order gives the
+     *   priority when more than one pattern can match the same path.
+     * @param options - 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.
      */
     constructor(mappings: RouteMapping[], { cacheSize }?: {
         cacheSize?: number;
     });
     /**
-     * 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.
      *
-     * @param path - URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`)
-     * @returns The mapped state ID, or `null` if no route matches
+     * @param path - The URL pathname. It can hold a query and a hash, for example `"/profile/123?ref=nav"`
+     * @returns The state ID of the path, or `null` when no route matches
      *
      * @example
      * ```typescript
@@ -115,19 +121,19 @@ export declare class RouteMap {
      */
     getStateIdByPath(path: string): string | null;
     /**
-     * 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.
      *
-     * @param stateId - State machine state ID (e.g., `"profile"`, `"#settings"`)
-     * @returns The registered path pattern, or `null` if the state ID is unknown
+     * @param stateId - The state ID of the state machine, for example `"profile"` or `"#settings"`
+     * @returns 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
      * ```
      */

package/dist/base-route-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0BH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,QAAQ;IACpB,gEAAgE;IAChE,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;;;;;;;OAeG;gBACS,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,SAAe,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAmCtF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB7C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD"}
+{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,QAAQ;IACpB,8EAA8E;IAC9E,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;;;;;;;;;OAiBG;gBACS,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,SAAe,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAoCtF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB7C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD"}