@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,11 +2,9 @@
 
 # @xmachines/play-solid-router
 
-SolidJS Router adapter for the XMachines Universal Player Architecture. Provides bidirectional synchronisation between a `PlayerActor`'s state machine routes and the browser URL via `@solidjs/router`.
+SolidJS Router adapter for the XMachines Universal Player Architecture. It keeps the state machine routes of a `PlayerActor` and the browser URL in step, in both directions, through `@solidjs/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.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-solid-router)
-
-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-solid-router)
 
 ## Installation
 
@@ -14,7 +12,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-solid-router
 ```
 
-**Peer dependencies** (must be installed separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add solid-js @solidjs/router xstate
@@ -38,6 +36,10 @@ actor.start();
 
 const routeMap = createRouteMap(myMachine);
 
+// Minimal app shell stub — a real app renders PlayUIProvider + PlayRenderer from
+// @xmachines/play-solid here (see the workspace-only @xmachines/play-solid-demo Shell)
+const MyApp = (props: { actor: typeof actor }) => <main />;
+
 const Layout: ParentComponent = () => {
 	const navigate = useNavigate();
 	const location = useLocation();
@@ -64,7 +66,7 @@ export default function App() {
 
 ### `PlayRouterProvider`
 
-A SolidJS component that wires a `PlayerActor` to Solid Router. It creates and connects a `SolidRouterBridge` on mount and disconnects it via `onCleanup` on unmount.
+This SolidJS component connects a `PlayerActor` to Solid Router. It creates and connects a `SolidRouterBridge` on mount. It disconnects the bridge with `onCleanup` on unmount.
 
 ```tsx
 interface PlayRouterProviderProps<TActor extends PlayActor> {
@@ -85,14 +87,17 @@ interface PlayRouterProviderProps<TActor extends PlayActor> {
 
 ### `SolidRouterBridge`
 
-Low-level class for manual integration. Extends `RouterBridgeBase` from `@xmachines/play-router` and uses Solid's `createEffect` for reactive router→actor sync.
+The low-level class for a manual integration. It extends `RouterBridgeBase` from `@xmachines/play-router`. It uses the Solid `createEffect` to send each router change to the actor.
 
-> **Important:** `connect()` must be called inside a Solid reactive owner (component or `createRoot`). Cleanup is not automatic — call `disconnect()` (or `dispose()`) explicitly, typically in `onCleanup()`.
+> **Important:** call `connect()` inside a Solid reactive owner: a component, or `createRoot`. The bridge does not clean up by itself. Call `disconnect()` or `dispose()` yourself, usually in `onCleanup()`.
 
 ```tsx
-import { useNavigate, useLocation, useParams, onCleanup } from "@solidjs/router";
+import { useNavigate, useLocation, useParams } from "@solidjs/router";
+import { onCleanup } from "solid-js";
 import { SolidRouterBridge, RouteMap } from "@xmachines/play-solid-router";
 
+// actor: your started player (see the Quick Start above)
+
 function App() {
 	const navigate = useNavigate();
 	const location = useLocation();
@@ -113,7 +118,7 @@ function App() {
 
 ### `createRouteMap(machine)`
 
-Factory that builds a `RouteMap` directly from an XState machine definition. Re-exported from `@xmachines/play-router`.
+This factory builds a `RouteMap` directly from an XState machine definition. It comes from `@xmachines/play-router`.
 
 ```ts
 import { createRouteMap } from "@xmachines/play-solid-router";
@@ -123,7 +128,7 @@ const routeMap = createRouteMap(myMachine);
 
 ### `RouteMap` / `RouteMapping`
 
-Bidirectional state ID ↔ URL path mapping. Re-exported from `@xmachines/play-router`.
+The bidirectional map between the state IDs and the URL paths. It comes from `@xmachines/play-router`.
 
 ```ts
 import { RouteMap } from "@xmachines/play-solid-router";
@@ -137,22 +142,22 @@ const routeMap = new RouteMap([
 
 ### Types
 
-| Export                    | Description                                                                                                                                                                                             |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PlayActor`               | `AbstractActor & Routable & Viewable` — canonical actor shape from `@xmachines/play-router`. Required by `PlayRouterProvider`, which renders the current view spec in addition to synchronizing routes. |
-| `RoutableActor`           | Deprecated alias for `PlayActor`. Use `PlayActor` from `@xmachines/play-router` in new code.                                                                                                            |
-| `AbstractActor`           | Re-exported from `@xmachines/play-actor` for convenience when typing renderer callbacks.                                                                                                                |
-| `SolidRouterHooks`        | Shape of the `router` prop: `{ navigate, location, params }`                                                                                                                                            |
-| `PlayRouterProviderProps` | Full props interface for `PlayRouterProvider`                                                                                                                                                           |
-| `PlayRouteEvent`          | Event type sent to the actor on URL change (`play.route`)                                                                                                                                               |
-| `RouterBridge`            | Interface implemented by `SolidRouterBridge`                                                                                                                                                            |
-| `RouteMapOptions`         | Options bag for `RouteMap` construction. Re-exported from `@xmachines/play-router`.                                                                                                                     |
+| Export                    | Description                                                                                                                                                                                                    |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PlayActor`               | `AbstractActor & Routable & Viewable` — the canonical actor shape from `@xmachines/play-router`. `PlayRouterProvider` requires it, because it renders the current view spec and also keeps the routes in step. |
+| `RoutableActor`           | Deprecated alias for `PlayActor`. Use `PlayActor` from `@xmachines/play-router` in new code.                                                                                                                   |
+| `AbstractActor`           | It comes from `@xmachines/play-actor`. Use it for the type of a renderer callback.                                                                                                                             |
+| `SolidRouterHooks`        | Shape of the `router` prop: `{ navigate, location, params }`                                                                                                                                                   |
+| `PlayRouterProviderProps` | Full props interface for `PlayRouterProvider`                                                                                                                                                                  |
+| `PlayRouteEvent`          | The event type that the bridge sends to the actor on a URL change (`play.route`)                                                                                                                               |
+| `RouterBridge`            | The interface that `SolidRouterBridge` implements                                                                                                                                                              |
+| `RouteMapOptions`         | The options object for the `RouteMap` constructor. It comes from `@xmachines/play-router`.                                                                                                                     |
 
 ## Usage Patterns
 
 ### Protected Routes and Guards
 
-Auth guards live entirely inside the state machine, preventing flashes of unauthorized content:
+The auth guards are inside the state machine only. Unauthorized content therefore never appears, not even for a moment:
 
 ```ts
 const machineConfig = {
@@ -168,13 +173,13 @@ const machineConfig = {
 };
 ```
 
-When a user navigates to `/dashboard` while unauthenticated:
+A user navigates to `/dashboard`, and the user is not authenticated:
 
 1. Solid Router updates the URL.
-2. Bridge intercepts and sends `play.route` to the actor.
-3. Actor evaluates the guard — denies transition, moves to `login` instead.
-4. Bridge observes new actor route (`/login`) via TC39 Signal.
-5. Bridge calls `navigate("/login")`.
+2. The bridge receives the change and sends `play.route` to the actor.
+3. The actor evaluates the guard. The guard refuses the transition, and the actor moves to `login`.
+4. The bridge reads the new actor route (`/login`) from the TC39 Signal.
+5. The bridge calls `navigate("/login")`.
 
 ### Dynamic Routes with Parameters
 
@@ -188,7 +193,7 @@ const routeMap = new RouteMap([
 // { type: "play.route", to: "#post", params: { userId: "123", postId: "456" }, query: {} }
 ```
 
-Path parameters are extracted from Solid's reactive `useParams()` proxy — no URLPattern polyfill is needed for parameterized routes.
+The bridge reads the path parameters from the reactive `useParams()` proxy of Solid. A parameterized route therefore does not need the URLPattern polyfill.
 
 ## Testing
 
@@ -202,7 +207,7 @@ pnpm --filter @xmachines/play-solid-router test
 pnpm test
 ```
 
-**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce:
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run in real Chromium through Playwright. They cover the asynchronous sequences that jsdom cannot reproduce:
 
 ```bash
 pnpm exec vitest --config vitest.browser.config.ts --project play-solid-router-browser

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

@@ -2,32 +2,33 @@
 
 # Class: RouteMap
 
-Defined in: [packages/play-router/src/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: [packages/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: [packages/play-router/src/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: [packages/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: [packages/play-router/src/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: [packages/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: [packages/play-router/src/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: [packages/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
 

package/api/@xmachines/play-solid-router/classes/SolidRouterBridge.md

@@ -2,17 +2,19 @@
 
 # Class: SolidRouterBridge
 
-Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid-router/src/solid-router-bridge.ts#L54)
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid-router/src/solid-router-bridge.ts#L58)
 
-SolidJS Router integration bridge extending RouterBridgeBase
+The SolidJS Router integration bridge. It extends RouterBridgeBase
 
-Implements RouterBridge protocol for SolidJS Router using Solid's reactive
-primitives. The actor→router direction uses TC39 Signal watcher (from base class).
-The router→actor direction uses Solid's createEffect for native reactivity.
+The class implements the RouterBridge protocol for SolidJS Router with the
+reactive primitives of Solid. The actor-to-router direction uses the TC39 Signal
+watcher of the base class. The router-to-actor direction uses the Solid
+createEffect function for a native reactivity.
 
-Path parameters are extracted from Solid's `useParams()` reactive proxy rather than
-re-parsing the URL with URLPattern. This means parameterized routes work without the
-URLPattern polyfill — Solid's router has already extracted the values.
+The bridge reads each path parameter from the reactive `useParams()` proxy of
+Solid. It does not parse the URL again with URLPattern. Therefore a
+parameterized route works without the URLPattern polyfill, because the router of
+Solid holds the values already.
 
 ## Extends
 
@@ -31,21 +33,21 @@ new SolidRouterBridge(
    routeMap): SolidRouterBridge;
 ```
 
-Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid-router/src/solid-router-bridge.ts#L75)
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid-router/src/solid-router-bridge.ts#L81)
 
-Create a SolidJS Router bridge
+Creates a SolidJS Router bridge
 
-**CRITICAL:** `connect()` must be called inside a Solid component where hooks are available.
+**CRITICAL:** call `connect()` inside a Solid component, where the hooks are available.
 
 #### Parameters
 
-| Parameter       | Type                                                                 | Description                                                                                                                                     |
-| --------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `solidNavigate` | `Navigator`                                                          | Result of useNavigate() hook                                                                                                                    |
-| `location`      | [`LocationLike`](../../play-router/interfaces/LocationLike.md)       | Result of useLocation() hook                                                                                                                    |
-| `params`        | `Params`                                                             | Result of useParams() hook — used directly for path parameter extraction, avoiding the URLPattern polyfill requirement for parameterized routes |
-| `actor`         | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | XMachines actor instance                                                                                                                        |
-| `routeMap`      | [`RouteMap`](RouteMap.md)                                            | Bidirectional state ID ↔ path mapping                                                                                                           |
+| Parameter       | Type                                                                 | Description                                                                                                                                                      |
+| --------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `solidNavigate` | `Navigator`                                                          | The result of the useNavigate() hook                                                                                                                             |
+| `location`      | [`LocationLike`](../../play-router/interfaces/LocationLike.md)       | The result of the useLocation() hook                                                                                                                             |
+| `params`        | `Params`                                                             | The result of the useParams() hook. The bridge reads each path parameter directly from it. A parameterized route therefore does not need the URLPattern polyfill |
+| `actor`         | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | The XMachines actor instance                                                                                                                                     |
+| `routeMap`      | [`RouteMap`](RouteMap.md)                                            | The bidirectional map between the state IDs and the paths                                                                                                        |
 
 #### Returns
 
@@ -63,21 +65,23 @@ Create a SolidJS Router bridge
 connect(): void;
 ```
 
-Defined in: [packages/play-router/src/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: [packages/play-router/src/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
 
@@ -95,11 +99,12 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [packages/play-router/src/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: [packages/play-router/src/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
 
@@ -111,15 +116,15 @@ Stops signal watching and unregisters framework-specific router listener.
 
 ---
 
-### dispose()
+### ~~dispose()~~
 
 ```ts
 dispose(): void;
 ```
 
-Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid-router/src/solid-router-bridge.ts#L187)
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid-router/src/solid-router-bridge.ts#L202)
 
-Dispose the bridge (alias for disconnect).
+Disposes of the bridge. This method is the alias of disconnect.
 
 #### Returns
 
@@ -130,3 +135,7 @@ Dispose the bridge (alias for disconnect).
 ```tsx
 onCleanup(() => bridge.dispose());
 ```
+
+#### Deprecated
+
+Use [disconnect](#disconnect). Will be removed in the next major.

package/api/@xmachines/play-solid-router/functions/createPlayRouterProvider.md

@@ -6,17 +6,18 @@
 function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(props) => any;
 ```
 
-Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid-router/src/create-play-router-provider.tsx#L68)
+Defined in: [packages/play-solid-router/src/create-play-router-provider.tsx:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid-router/src/create-play-router-provider.tsx#L69)
 
-Create a Solid `PlayRouterProvider` component bound to a specific bridge class.
+Creates a Solid `PlayRouterProvider` component of one bridge class.
 
-The returned component connects a `PlayerActor` to the framework router,
-keeping actor state and browser URL in sync bidirectionally.
+The component of the return value connects a `PlayerActor` to the framework
+router. It keeps the actor state and the browser URL in step, in both directions.
 
-The bridge is created synchronously at component evaluation time (Solid's
-execution model) and torn down via `onCleanup` when the component is disposed.
-Unlike React, prop stability is not a concern — Solid's `props` accessor is
-already reactive and the bridge is created once per component instance.
+The component creates the bridge synchronously, during its own evaluation, because
+this is the execution model of Solid. It disconnects the bridge in `onCleanup`,
+when Solid disposes of the component. React is different: the stability of a prop
+is no concern here, because the `props` accessor of Solid is reactive already, and
+the component creates the bridge one time for each of its instances.
 
 ## Type Parameters
 
@@ -26,14 +27,15 @@ already reactive and the bridge is created once per component instance.
 
 ## Parameters
 
-| Parameter    | Type                                                                                         | Description                                                            |
-| ------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | Bridge class constructed as `new BridgeCtor(router, actor, routeMap)`. |
+| Parameter    | Type                                                                                         | Description                                                                            |
+| ------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | The bridge class. The provider builds it as `new BridgeCtor(router, actor, routeMap)`. |
 
 ## Returns
 
-A `PlayRouterProvider` component, generic over the actor type so the
-`renderer` callback receives the same concrete actor type that was passed in.
+A `PlayRouterProvider` component. It is generic over the actor type.
+Therefore the `renderer` callback receives the same concrete actor type as the
+prop.
 
 \<`TActor`\>(`props`) => `any`
 

package/api/@xmachines/play-solid-router/functions/createRouteMap.md

@@ -6,27 +6,28 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [packages/play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [packages/play-router/src/create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L47)
 
-Create a `RouteMap` from an XState state machine.
+Creates a `RouteMap` from an XState state machine.
 
-Extracts all routable states (those with `meta.route`) and builds a bidirectional
-path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
-subclasses to translate browser URL changes into `play.route` actor events and
-vice-versa.
+The function reads every state with a route, which means each state with a
+`meta.route` field. It then builds the lookup structure between a path and a
+stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
+converts each change of the browser URL into a `play.route` actor event, and each
+actor route into a URL.
 
 ## Parameters
 
-| Parameter  | Type                                                                      | Description                                                                                                         |
-| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
-| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
+| Parameter  | Type                                                                      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine, with a `meta.route` annotation on each state with a route.                                         |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | The optional configuration. Give `{ cacheSize }` to change the default size of the LRU cache of the parameterized path lookups. |
 
 ## Returns
 
 [`RouteMap`](../classes/RouteMap.md)
 
-A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ## Example