@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,14 +2,15 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L51)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L54)
 
-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
 
@@ -21,7 +22,7 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
-| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L55) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L53) |
+| Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L56) |

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

@@ -2,21 +2,23 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:360](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L360)
+Defined in: [play-router/src/types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L358)
 
-RouterBridge interface for runtime infrastructure adapters
+The RouterBridge interface of a runtime infrastructure adapter
 
-Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
-the Actor. Infrastructure "bridges" to the Actor by observing its signals and
-managing its own lifecycle accordingly.
+The interface defines the connection of the lifecycle between the infrastructure,
+for example a framework router, and the Actor. The infrastructure builds a "bridge"
+to the Actor: it observes the signals of the Actor, and it manages its own
+lifecycle accordingly.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
-a unidirectional observation pattern. Infrastructure connects to observe Actor signals
-(currentRoute, currentView, state) and reflects changes without making state decisions.
+**Architectural context:** the interface implements **Passive Infrastructure
+(INV-04)**, because it gives an observation in one direction. The infrastructure
+connects to observe the signals of the Actor (currentRoute, currentView, and
+state), and it reflects each change. It makes no decision about the state.
 
 ## Example
 
-Framework router bridge implementation
+The implementation of a framework router bridge
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
@@ -26,7 +28,7 @@ class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
-		// Start observing actor.currentRoute signal
+		// Start the observation of the actor.currentRoute signal
 		this.watcher = new Signal.subtle.Watcher(() => {
 			const route = actor.currentRoute.get();
 			if (route) router.navigate(route);
@@ -35,7 +37,7 @@ class MyRouterBridge implements RouterBridge {
 	}
 
 	async disconnect(): Promise<void> {
-		// Stop observing, cleanup watchers
+		// Stop the observation, and clean the watchers up
 		this.watcher?.unwatch(actor.currentRoute);
 		this.watcher = null;
 	}
@@ -44,7 +46,7 @@ class MyRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+[Play RFC](../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -54,25 +56,26 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L376)
+Defined in: [play-router/src/types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L375)
 
-Connect the router bridge to the Actor
+Connects the router bridge to the Actor
 
-Called when Infrastructure should begin observing Actor signals and
-synchronizing its state (e.g., browser URL) with Actor state.
+The infrastructure calls it when it must start the observation of the Actor
+signals, and when it must bring its own state, for example the browser URL, in line
+with the Actor state.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when connection is established, or void for synchronous connection
+The promise that resolves after the connection, or void for a synchronous connection
 
 #### Example
 
 ```typescript
 const bridge: RouterBridge = createBridge(actor, router);
 await bridge.connect();
-// Bridge now observing actor.currentRoute signal
+// The bridge observes the actor.currentRoute signal now
 ```
 
 ---
@@ -83,22 +86,22 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L392)
+Defined in: [play-router/src/types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L391)
 
-Disconnect the router bridge from the Actor
+Disconnects the router bridge from the Actor
 
-Called when Infrastructure should stop observing and clean up resources
-(e.g., signal watchers, event listeners).
+The infrastructure calls it when it must stop the observation and free its
+resources, for example a signal watcher and an event listener.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when disconnection is complete, or void for synchronous disconnection
+The promise that resolves after the disconnection, or void for a synchronous disconnection
 
 #### Example
 
 ```typescript
 await bridge.disconnect();
-// Bridge stopped observing, resources cleaned up
+// The bridge stopped its observation, and it freed its resources
 ```

package/api/@xmachines/play-sveltekit-router/type-aliases/RoutableActor.md

@@ -6,4 +6,4 @@
 type RoutableActor = AbstractActor<AnyActorLogic> & Routable;
 ```
 
-Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-sveltekit-router/src/types.ts#L10)
+Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/types.ts#L10)

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

@@ -1,12 +1,10 @@
 [API](../../README.md) / @xmachines/play-tanstack-react-router
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-tanstack-react-router
 
-TanStack Router (React) adapter for XMachines Play — synchronizes browser URL with actor state through passive infrastructure.
+TanStack Router (React) adapter for XMachines Play. It keeps the browser URL and the actor state in step through passive infrastructure.
 
-Part of the [xmachines-js monorepo](../../README.md).
+[![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-tanstack-react-router)
 
 ## Installation
 
@@ -14,41 +12,64 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-tanstack-react-router
 ```
 
-**Peer dependencies** (install separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add @tanstack/react-router react react-dom xstate
 ```
 
-Requires:
+The adapter requires:
 
 - `@tanstack/react-router` `^1.168.8`
 - `react` `^18.0.0` or `^19.0.0`
 - `react-dom` `^18.0.0` or `^19.0.0`
-- `xstate` `^6.0.0-alpha.19`
+- `xstate` `^5.31.0`
 
 ## Usage
 
 ### `PlayRouterProvider` — React component (recommended)
 
-`PlayRouterProvider` is the primary integration point. It creates a `TanStackReactRouterBridge` on mount, keeps it connected for the component lifetime, and tears it down on unmount.
+`PlayRouterProvider` is the primary integration point. It creates a `TanStackReactRouterBridge` on mount. It keeps the bridge connected for the life of the component. It disconnects the bridge on unmount.
 
 ```tsx
-import { useMemo, useEffect } from "react";
+import { useMemo, useEffect, useState } from "react";
+import { createMachine } from "xstate";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
-import {
-	PlayRouterProvider,
-	createRouteMapFromTree,
-	extractMachineRoutes,
-} from "@xmachines/play-tanstack-react-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-react-router";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { useSignalEffect } from "@xmachines/play-react";
+
+// Any machine whose states declare `meta.route` (plus an explicit `id`) is routable.
+// formatPlayRouteTransitions() generates the root-level `play.route` handlers that
+// let the bridge drive the machine from URL changes.
+const machine = createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+		},
+	}),
+);
+
+const createPlayer = definePlayer({ machine });
+type AppActor = ReturnType<typeof createPlayer>;
+
+// Minimal shell: mirrors the actor's route signal into React state. A full app
+// renders <PlayUIProvider> + <PlayRenderer> from @xmachines/play-react here
+// instead — see examples/demo for the complete Shell.
+function Shell({ actor }: { actor: AppActor }) {
+	const [route, setRoute] = useState(actor.currentRoute.get());
+	useSignalEffect(() => setRoute(actor.currentRoute.get()), [actor]);
+	return <p>Current route: {route}</p>;
+}
 
 function createAppRuntime() {
-	const actor = definePlayer({ machine, catalog })();
+	const actor = createPlayer();
 	actor.start();
 
-	const routeTree = extractMachineRoutes(machine);
-	const routeMap = createRouteMapFromTree(routeTree);
+	const routeMap = createRouteMap(machine);
 	const rootRoute = createRootRoute();
 	const router = createRouter({ routeTree: rootRoute });
 
@@ -66,32 +87,28 @@ export function App() {
 			actor={actor}
 			router={router}
 			routeMap={routeMap}
-			renderer={(currentActor, currentRouter) => (
-				<Shell actor={currentActor} router={currentRouter} />
-			)}
+			renderer={(currentActor) => <Shell actor={currentActor} />}
 		/>
 	);
 }
 ```
 
-> **Stable references:** `actor`, `router`, and `routeMap` must be stable across renders. If any prop changes identity, the bridge disconnects and reconnects. Use `useMemo` to create them once.
+> **Stable references:** `actor`, `router`, and `routeMap` must stay stable across the renders. If one prop gets a new identity, the bridge disconnects, then it connects again. Use `useMemo` to create each prop one time.
 
-### `TanStackReactRouterBridge` — headless class
+### `TanStackReactRouterBridge` — the bridge class
 
-Use the bridge directly when you don't need the React wrapper, or when integrating with a custom lifecycle:
+Use the bridge directly when you do not need the React wrapper, or when you integrate it with a custom lifecycle:
 
 ```typescript
-import { createRouter } from "@tanstack/react-router";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import {
-	TanStackReactRouterBridge,
-	createRouteMapFromTree,
-	extractMachineRoutes,
-} from "@xmachines/play-tanstack-react-router";
+import { TanStackReactRouterBridge, createRouteMap } from "@xmachines/play-tanstack-react-router";
+import { machine } from "./machine.js"; // the routable machine from the example above
 
-const router = createRouter({ routeTree });
-const actor = definePlayer({ machine, catalog })();
-const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
+const router = createRouter({ routeTree: createRootRoute() });
+const actor = definePlayer({ machine })();
+actor.start();
+const routeMap = createRouteMap(machine);
 
 const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
@@ -104,7 +121,7 @@ bridge.disconnect();
 
 ### `TanStackReactRouterBridge`
 
-Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements bidirectional sync between actor state signals and TanStack Router history.
+This class extends `RouterBridgeBase` from `@xmachines/play-router`. It keeps the actor state signals and the TanStack Router history in step, in both directions.
 
 ```typescript
 class TanStackReactRouterBridge extends RouterBridgeBase {
@@ -115,11 +132,11 @@ class TanStackReactRouterBridge extends RouterBridgeBase {
 }
 ```
 
-Subscribes to `router.history` (not `router.subscribe("onBeforeLoad")`) so that back/forward browser navigation (popstate events) are captured even without a `<RouterProvider>` mounted.
+The bridge subscribes to `router.history`, not to `router.subscribe("onBeforeLoad")`. Therefore the bridge also receives a browser BACK or FORWARD navigation (a popstate event) when no `<RouterProvider>` is mounted.
 
 ### `PlayRouterProvider`
 
-React component that wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
+This React component wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
 
 ```typescript
 interface PlayRouterProviderProps<TActor> {
@@ -132,7 +149,7 @@ interface PlayRouterProviderProps<TActor> {
 
 ### `TanStackRouterLike`
 
-Structural type for the router instance — accepts any object with the required `navigate` and `history` shape, making it testable without creating a full TanStack Router:
+The structural type of the router instance. It accepts every object that has the necessary `navigate` and `history` shape. A test can therefore use a stub in place of a complete TanStack Router:
 
 ```typescript
 type TanStackRouterLike = {
@@ -149,7 +166,7 @@ type TanStackRouterLike = {
 
 ### `RouteNavigateEvent`
 
-Event sent to the actor when the browser navigates:
+The event that the bridge sends to the actor when the browser navigates:
 
 ```typescript
 interface RouteNavigateEvent {
@@ -163,7 +180,7 @@ interface RouteNavigateEvent {
 ```typescript
 // Route map construction
 RouteMap
-createRouteMap(mappings: RouteMapping[]): RouteMap
+createRouteMap(machine, options?): RouteMap
 createRouteMapFromTree(routeTree): RouteMap
 extractMachineRoutes(machine): RouteTree
 
@@ -178,10 +195,10 @@ type PlayRouteEvent
 
 The bridge implements the **Passive Infrastructure** invariant from the XMachines RFC:
 
-1. **Actor → Router:** When `actor.currentRoute` signal changes, the bridge calls `router.navigate({ to: path })`. The URL updates to reflect the new actor state.
-2. **Router → Actor:** When `router.history.subscribe` fires (link clicks, `back`/`forward` buttons, `history.pushState`), the bridge sends a `play.route` event to the actor. The actor's guards decide whether navigation is valid — the router never enforces business logic.
-3. **Circular update prevention:** A `lastSyncedPath` guard suppresses round-trip updates so an actor → router navigation does not trigger a redundant router → actor send.
-4. **Deep-link and restore:** On `connect()`, the bridge reads `router.history.location.pathname` (which reflects `window.location` immediately, before `router.load()` runs) and determines whether to sync the actor from the URL (deep-link) or push the actor's restored route to the URL (snapshot restore).
+1. **Actor → Router:** when the `actor.currentRoute` signal changes, the bridge calls `router.navigate({ to: path })`. The URL then shows the new actor state.
+2. **Router → Actor:** when `router.history.subscribe` fires, the bridge sends a `play.route` event to the actor. A link click, a BACK or FORWARD button, and a call to `history.pushState` each cause this. The guards of the actor decide if the navigation is valid. The router never enforces the business logic.
+3. **Circular update prevention:** the `lastSyncedPath` guard stops a return update. An actor-to-router navigation therefore does not cause an unnecessary router-to-actor send.
+4. **Deep-link and restore:** on `connect()`, the bridge reads `router.history.location.pathname`. That value shows `window.location` at once, before `router.load()` runs. The bridge then makes a decision: it sets the actor state from the URL (a deep link), or it writes the restored route of the actor to the URL (a snapshot restore).
 
 ## Testing
 
@@ -201,16 +218,16 @@ Tests cover RouterBridge protocol compliance, actor ↔ router bidirectional syn
 
 ## Demo
 
-A runnable React + TanStack Router integration demo is available under `examples/demo/`. To run it from the repository root:
+`examples/demo/` holds a runnable demo of the React and TanStack Router integration. Run it from the repository root:
 
 ```bash
 pnpm install
 pnpm --filter @xmachines/play-tanstack-react-router-demo run dev
 ```
 
-Then open `http://localhost:3000`.
+Then open `http://localhost:3011`.
 
-The demo shows actor-authoritative routing with a shared auth machine: TanStack Router updates the URL, `PlayRouterProvider` translates it to a `play.route` event, and the actor's guards decide whether access is permitted.
+The demo shows actor-authoritative routing with a shared auth machine. TanStack Router updates the URL. `PlayRouterProvider` converts the update into a `play.route` event. The guards of the actor then permit the access, or they refuse it.
 
 ## License
 
@@ -218,8 +235,9 @@ MIT — see [LICENSE](./LICENSE).
 
 @xmachines/play-tanstack-react-router
 
-TanStack Router adapter for XMachines Play architecture.
-Synchronizes browser URL with actor state through passive infrastructure.
+TanStack Router adapter for the XMachines Play architecture.
+It keeps the browser URL and the actor state in step through passive
+infrastructure.
 
 ## Classes
 
@@ -234,7 +252,7 @@ Synchronizes browser URL with actor state through passive infrastructure.
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
-- [RouteNavigateEvent](interfaces/RouteNavigateEvent.md)
+- [~~RouteNavigateEvent~~](interfaces/RouteNavigateEvent.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases

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

@@ -2,32 +2,33 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [play-router/src/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: [play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L127)
+Defined in: [play-router/src/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: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [play-router/src/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: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [play-router/src/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