@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,11 +2,9 @@
 
 # @xmachines/play-sveltekit-router
 
-SvelteKit router adapter for the XMachines Universal Player Architecture. Provides bidirectional synchronisation between a `RoutableActor`'s state machine routes and the browser URL via SvelteKit's `$app/navigation`.
+SvelteKit router adapter for the XMachines Universal Player Architecture. It keeps the state machine routes of a `RoutableActor` and the browser URL in step, in both directions, through the `$app/navigation` module of SvelteKit.
 
-[![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-sveltekit-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-sveltekit-router)
 
 ## Installation
 
@@ -14,7 +12,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-sveltekit-router
 ```
 
-**Peer dependencies** (must be installed separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add @sveltejs/kit svelte xstate
@@ -29,6 +27,7 @@ pnpm add @sveltejs/kit svelte xstate
 ## Quick Start
 
 ```typescript
+import { onDestroy } from "svelte";
 import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
 import { definePlayer } from "@xmachines/play-xstate";
 import { myMachine } from "./machine.js";
@@ -48,27 +47,29 @@ const disconnect = connectRouter({ actor, routeMap });
 onDestroy(() => disconnect());
 ```
 
-The bridge synchronises in both directions:
+The bridge works in both directions:
 
-- **URL → actor:** SvelteKit `afterNavigate` events are translated to `play.route` events and sent to the actor.
-- **Actor → URL:** Actor `currentRoute` signal changes are reflected to the browser URL via `goto()`.
+- **URL → actor:** the bridge converts each SvelteKit `afterNavigate` event into a `play.route` event, then sends it to the actor.
+- **Actor → URL:** the bridge writes each change of the actor `currentRoute` signal to the browser URL with `goto()`.
 
 ## Usage
 
 ### `connectRouter(options)` — high-level API
 
-The primary integration point. Instantiates a `SvelteKitRouterBridge`, calls `connect()`, and returns a cleanup function.
+This function is the primary integration point. It creates a `SvelteKitRouterBridge`, calls `connect()`, and returns a cleanup function.
 
 ```typescript
+import { onDestroy } from "svelte";
 import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
 
+// machine and actor as in the Quick Start above
 const routeMap = createRouteMap(machine);
 
 // In a Svelte component or SvelteKit layout
 const disconnect = connectRouter({ actor, routeMap });
 
-// Pass an explicit location for SSR or test environments
-const disconnect = connectRouter({
+// Or pass an explicit location for SSR or test environments
+const disconnectSsr = connectRouter({
 	actor,
 	routeMap,
 	location: { pathname: "/dashboard", search: "?tab=stats" },
@@ -80,19 +81,20 @@ onDestroy(() => disconnect());
 
 **`ConnectRouterOptions`:**
 
-| Property   | Type                   | Required | Description                                                                                                                 |
-| ---------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `actor`    | `RoutableActor`        | Yes      | The XMachines actor to synchronise with the router                                                                          |
-| `routeMap` | `RouteMap`             | Yes      | Bidirectional state ID ↔ URL path mapping                                                                                   |
-| `location` | `LocationLike \| null` | No       | Location stub for initial URL reads. Defaults to `globalThis.location`. Pass a mock in tests or a stub in SSR environments. |
+| Property   | Type                   | Required | Description                                                                                                                                |
+| ---------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `actor`    | `RoutableActor`        | Yes      | The XMachines actor that the bridge keeps in step with the router                                                                          |
+| `routeMap` | `RouteMap`             | Yes      | The bidirectional map between the state IDs and the URL paths                                                                              |
+| `location` | `LocationLike \| null` | No       | The location stub for the initial URL reads. The default is `globalThis.location`. Give a mock in a test, or a stub in an SSR environment. |
 
 ### `SvelteKitRouterBridge` — low-level class
 
-Extends `RouterBridgeBase` from `@xmachines/play-router`. Use directly when you need fine-grained control over the connection lifecycle.
+This class extends `RouterBridgeBase` from `@xmachines/play-router`. Use it directly when you need more control over the connection lifecycle.
 
 ```typescript
 import { SvelteKitRouterBridge, createRouteMap } from "@xmachines/play-sveltekit-router";
 
+// machine and actor as in the Quick Start above
 const routeMap = createRouteMap(machine);
 const bridge = new SvelteKitRouterBridge(actor, routeMap, location);
 bridge.connect();
@@ -104,12 +106,12 @@ bridge.disconnect();
 **SvelteKit integration details:**
 
 - `navigateRouter` → `goto(path, { noScroll: true, keepFocus: true })`
-- `watchRouterChanges` → registers an `afterNavigate` callback via an indirection cell, avoiding direct `this` capture
-- `unwatchRouterChanges` → nulls the indirection cell, releasing the bridge reference before component unmount (since SvelteKit provides no programmatic cancel API for `afterNavigate`)
+- `watchRouterChanges` → registers an `afterNavigate` callback through an indirection cell, which prevents a direct capture of `this`
+- `unwatchRouterChanges` → sets the indirection cell to null, which releases the bridge reference before the component unmounts (SvelteKit has no API to cancel `afterNavigate`)
 
 ### `createRouteMap(machine)`
 
-Factory that builds a `RouteMap` from an XState machine definition. State route patterns are read from `state.meta.route`.
+This factory builds a `RouteMap` from an XState machine definition. It reads each route pattern from `state.meta.route`.
 
 ```typescript
 import { createRouteMap } from "@xmachines/play-sveltekit-router";
@@ -130,7 +132,7 @@ const routeMap = createRouteMap(machine);
 
 ### `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`.
 
 ```typescript
 import { RouteMap } from "@xmachines/play-sveltekit-router";
@@ -146,22 +148,23 @@ const routeMap = new RouteMap([
 
 ### Exported symbols
 
-| Export                 | Kind     | Description                                                                                                    |
-| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
-| `connectRouter`        | function | High-level factory — connects the SvelteKit router to an actor, returns a cleanup function                     |
-| `ConnectRouterOptions` | type     | Options bag for `connectRouter`                                                                                |
-| `createRouteMap`       | function | Builds a `RouteMap` from an XState machine definition                                                          |
-| `RouteMap`             | class    | Bidirectional state ID ↔ URL path mapping (re-exported from `@xmachines/play-router`)                          |
-| `RouteMapping`         | type     | Single `{ stateId, path }` entry for `RouteMap` construction                                                   |
-| `RouteMapOptions`      | type     | Options for `RouteMap` construction                                                                            |
-| `LocationLike`         | type     | Minimal `{ pathname, search }` interface for location stubs                                                    |
-| `PlayRouteEvent`       | type     | Event sent to the actor on URL change (`{ type: "play.route", to, params?, query? }`)                          |
-| `RouterBridge`         | type     | Interface implemented by `SvelteKitRouterBridge`                                                               |
-| `RoutableActor`        | type     | Minimal actor interface from `@xmachines/play-router` — `currentRoute`, `initialRoute`, `send(PlayRouteEvent)` |
+| Export                  | Kind     | Description                                                                                                    |
+| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| `connectRouter`         | function | High-level factory — connects the SvelteKit router to an actor, returns a cleanup function                     |
+| `SvelteKitRouterBridge` | class    | The low-level bridge class. It extends `RouterBridgeBase`. Use it directly for full lifecycle control          |
+| `ConnectRouterOptions`  | type     | The options object for `connectRouter`                                                                         |
+| `createRouteMap`        | function | Builds a `RouteMap` from an XState machine definition                                                          |
+| `RouteMap`              | class    | Bidirectional state ID ↔ URL path mapping (re-exported from `@xmachines/play-router`)                          |
+| `RouteMapping`          | type     | Single `{ stateId, path }` entry for `RouteMap` construction                                                   |
+| `RouteMapOptions`       | type     | Options for `RouteMap` construction                                                                            |
+| `LocationLike`          | type     | Minimal `{ pathname, search }` interface for location stubs                                                    |
+| `PlayRouteEvent`        | type     | The event that the bridge sends to the actor on a URL change (`{ type: "play.route", to, params?, query? }`)   |
+| `RouterBridge`          | type     | The interface that `SvelteKitRouterBridge` implements                                                          |
+| `RoutableActor`         | type     | Minimal actor interface from `@xmachines/play-router` — `currentRoute`, `initialRoute`, `send(PlayRouteEvent)` |
 
 ## Demo
 
-A runnable Svelte 5 + SvelteKit router adapter demo is available in [`examples/demo/`](../../../examples/@xmachines/play-sveltekit-router-demo/README.md). To run it from the monorepo root:
+[`examples/demo/`](../../../examples/@xmachines/play-sveltekit-router-demo/README.md) holds a runnable Svelte 5 and SvelteKit demo of the adapter. Run it from the monorepo root:
 
 ```bash
 pnpm install
@@ -191,6 +194,7 @@ MIT — see [LICENSE](LICENSE).
 ## Classes
 
 - [RouteMap](classes/RouteMap.md)
+- [SvelteKitRouterBridge](classes/SvelteKitRouterBridge.md)
 
 ## Interfaces
 

package/api/@xmachines/play-sveltekit-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/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/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/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/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
 

package/api/@xmachines/play-sveltekit-router/classes/SvelteKitRouterBridge.md

@@ -0,0 +1,132 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / SvelteKitRouterBridge
+
+# Class: SvelteKitRouterBridge
+
+Defined in: [play-sveltekit-router/src/sveltekit-router-bridge.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/sveltekit-router-bridge.ts#L40)
+
+The SvelteKit router bridge — it connects the SvelteKit navigation to RouterBridgeBase.
+
+It implements the three abstract methods:
+
+- `navigateRouter` → `goto(path, { noScroll: true, keepFocus: true })`
+- `watchRouterChanges` → an `afterNavigate()` subscription through an indirection cell
+- `unwatchRouterChanges` → it sets the cell to null. This releases the bridge
+  reference of the registered closure before the component unmounts
+
+It overrides two optional hooks:
+
+- `getInitialRouterPath` → `loc.pathname`
+- `getInitialRouterSearch` → `loc.search`
+
+The bridge inherits the restore-or-deeplink detection and the `lastSyncedPath`
+echo suppression from `RouterBridgeBase`.
+
+## Param
+
+**actor**
+
+A `Routable` actor.
+
+## Param
+
+**routeMap**
+
+The bidirectional route map.
+
+## Param
+
+**loc**
+
+The location-like object for the initial URL reads. The default
+is `globalThis.location`. Give a mock in a test, or a stub in an SSR
+environment.
+
+## Extends
+
+- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new SvelteKitRouterBridge(
+   actor,
+   routeMap,
+   loc?): SvelteKitRouterBridge;
+```
+
+Defined in: [play-sveltekit-router/src/sveltekit-router-bridge.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/sveltekit-router-bridge.ts#L57)
+
+#### Parameters
+
+| Parameter  | Type                                                                 |
+| ---------- | -------------------------------------------------------------------- |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) |
+| `routeMap` | [`RouteMap`](RouteMap.md)                                            |
+| `loc`      | [`LocationLike`](../interfaces/LocationLike.md) \| `null`            |
+
+#### Returns
+
+`SvelteKitRouterBridge`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: [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)
+
+Connects the router bridge to the Actor.
+
+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.
+
+The order of these steps is part of the contract of the bridge:
+
+- 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`
+
+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
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: [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)
+
+Disconnects the router bridge from the Actor.
+
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)

package/api/@xmachines/play-sveltekit-router/functions/connectRouter.md

@@ -6,11 +6,11 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-sveltekit-router/src/connect-router.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-sveltekit-router/src/connect-router.ts#L27)
+Defined in: [play-sveltekit-router/src/connect-router.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/connect-router.ts#L28)
 
-Connect SvelteKit router to actor.
+Connects the SvelteKit router to an actor.
 
-Returns a cleanup function. The public API surface is unchanged (D-14).
+It returns a cleanup function. The public API surface stays as it was (D-14).
 
 ## Parameters
 

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

@@ -6,27 +6,28 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [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: [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
 

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

@@ -2,12 +2,12 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-sveltekit-router/src/connect-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-sveltekit-router/src/connect-router.ts#L4)
+Defined in: [play-sveltekit-router/src/connect-router.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/connect-router.ts#L4)
 
 ## Properties
 
-| Property                                   | Modifier   | Type                                                                 | Description                                                                                                                        | Defined in                                                                                                                                                          |
-| ------------------------------------------ | ---------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`        | `readonly` | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-sveltekit-router/src/connect-router.ts#L5)   |
-| <a id="property-location"></a> `location?` | `readonly` | [`LocationLike`](LocationLike.md) \| `null`                          | Location-like object for initial URL reads. Defaults to `globalThis.location`. Pass a mock in tests or a stub in SSR environments. | [play-sveltekit-router/src/connect-router.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-sveltekit-router/src/connect-router.ts#L11) |
-| <a id="property-routemap"></a> `routeMap`  | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                 | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-sveltekit-router/src/connect-router.ts#L6)   |
+| Property                                   | Modifier   | Type                                                                 | Description                                                                                                                                       | Defined in                                                                                                                                                          |
+| ------------------------------------------ | ---------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`        | `readonly` | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | -                                                                                                                                                 | [play-sveltekit-router/src/connect-router.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/connect-router.ts#L5)   |
+| <a id="property-location"></a> `location?` | `readonly` | [`LocationLike`](LocationLike.md) \| `null`                          | The location-like object for the initial URL reads. The default is `globalThis.location`. Give a mock in a test, or a stub in an SSR environment. | [play-sveltekit-router/src/connect-router.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/connect-router.ts#L12) |
+| <a id="property-routemap"></a> `routeMap`  | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                 | -                                                                                                                                                 | [play-sveltekit-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-sveltekit-router/src/connect-router.ts#L6)   |

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

@@ -2,19 +2,19 @@
 
 # Interface: LocationLike
 
-Defined in: [play-router/src/types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L414)
+Defined in: [play-router/src/types.ts:432](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L432)
 
-Minimal location interface required by adapters that read the current URL at
-`connect()` time. Injectable for SSR and testing — pass a mock instead of the
-global `location` when the DOM is unavailable.
+The minimal location interface of an adapter that reads the current URL at the
+moment of `connect()`. You can inject it for SSR and for a test: give a mock in
+place of the global `location` when no DOM is available.
 
-Defined structurally (no `Location` reference) so this package compiles without
-the DOM lib.
+The definition is structural, and it holds no reference to `Location`. This package
+therefore compiles without the DOM lib.
 
 ## Example
 
 ```typescript
-// SSR / test — injected mock
+// SSR or a test — an injected mock
 const mockLoc: LocationLike = { pathname: "/dashboard", search: "?tab=posts" };
 connectRouter({ actor, routeMap, location: mockLoc });
 ```
@@ -23,5 +23,5 @@ connectRouter({ actor, routeMap, location: mockLoc });
 
 | Property                                  | Modifier   | Type     | Defined in                                                                                                                      |
 | ----------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [play-router/src/types.ts:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L415) |
-| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:416](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L416) |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [play-router/src/types.ts:433](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L433) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:434](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L434) |