@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/api/@xmachines/play-svelte-spa-router/interfaces/PlayRouteEvent.md

@@ -2,57 +2,62 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:244](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L244)
+Defined in: [play-router/src/types.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L237)
 
-Enhanced routing event with parameter and query support
+The routing event, with its parameters and its query
 
-Unified routing event used throughout the Play architecture. Supports parameter-aware
-navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+This is the one routing event of the complete Play architecture. It supports a
+navigation that knows the parameters, for example `/profile/:userId`, for a dynamic
+route segment.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
-user navigation intent that the Actor evaluates through guards. Infrastructure proposes
-via `play.route` events, Actor decides via state machine transitions.
+**Architectural context:** the event implements **Passive Infrastructure
+(INV-04)**, because it holds the navigation intent of the user, and the Actor then
+evaluates that intent with its guards. The infrastructure makes a request with a
+`play.route` event, and the Actor decides with a transition of its state machine.
 
-**Browser Navigation Flow:**
+**The flow of a browser navigation:**
 
-1. Browser fires `popstate`
-2. Router adapter resolves URL to route target
-3. Adapter sends `PlayRouteEvent` to Actor
-4. Actor validates transition via state machine guards
+1. The browser fires `popstate`
+2. The router adapter resolves the URL to a route target
+3. The adapter sends a `PlayRouteEvent` to the Actor
+4. The Actor checks the transition with the guards of its state machine
 
 ## Param
 
 **type**
 
-Event discriminator (always "play.route")
+The discriminator of the event. It is always "play.route"
 
 ## Param
 
 **to**
 
-Target state ID with # prefix (e.g., '#home', '#profile')
+The target state ID, with a # prefix, for example '#home' or '#profile'
 
 ## Param
 
 **params**
 
-Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+The route parameters of the path only, from the URL path, for
+example `{ userId: '123' }` of `/profile/123`. The `query` field holds the query
+parameters separately.
 
 ## Param
 
 **query**
 
-Query parameters only (isolated from path params)
+The query parameters only. They stay separate from the params of the path
 
 ## Param
 
 **match**
 
-Full URLPattern match result for debugging/observability (optional)
+The complete match result of URLPattern, for the debug work and for
+the observability. It is optional
 
 ## Examples
 
-Combining base and routing events
+The base event and the routing event together
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
@@ -61,7 +66,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 type AppEvent = PlayEvent | PlayRouteEvent;
 ```
 
-Basic navigation to a route
+A basic navigation to a route
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -73,7 +78,7 @@ const event: PlayRouteEvent = {
 actor.send(event);
 ```
 
-Navigation with route parameters
+A navigation with route parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -84,10 +89,10 @@ const event: PlayRouteEvent = {
 	params: { userId: "123" },
 };
 actor.send(event);
-// Resolves to route: /profile/123
+// It resolves to the route /profile/123
 ```
 
-Navigation with query parameters
+A navigation with query parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -95,11 +100,11 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Path-only route parameter
-	query: { tab: "security" }, // Query-only
+	params: { section: "profile" }, // a route parameter of the path only
+	query: { tab: "security" }, // the query only
 };
 actor.send(event);
-// Resolves to route: /settings/profile?tab=security
+// It resolves to the route /settings/profile?tab=security
 ```
 
 ## See
@@ -108,9 +113,10 @@ actor.send(event);
 
 ## Remarks
 
-Use `play.route` when you need parameter-aware navigation with the `route: {}`
-config pattern on your state machine nodes. The `match` field exposes the full
-URLPatternResult for advanced use cases (debugging, pattern analysis).
+Use `play.route` when you need a navigation that knows the parameters, with the
+`route: {}` config pattern on the nodes of your state machine. The `match` field
+gives you the complete URLPatternResult, for an advanced use such as a debug or an
+analysis of the pattern.
 
 ## Indexable
 
@@ -120,10 +126,10 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
-| -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L249) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:247](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L247) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L248) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:246](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L246) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:245](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L245) |
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L242) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L240) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L241) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L239) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L238) |

package/api/@xmachines/play-svelte-spa-router/interfaces/RouteMapOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L9)
 
-Options for `createRouteMap` and `createRouteMapFromTree`.
+The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                  |
-| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/create-route-map.ts#L20) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L21) |

package/api/@xmachines/play-svelte-spa-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-svelte-spa-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-svelte-spa-router/interfaces/WindowLike.md

@@ -2,22 +2,22 @@
 
 # Interface: WindowLike
 
-Defined in: [play-router/src/types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L413)
+Defined in: [play-router/src/types.ts:412](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L412)
 
-Minimal window interface required by adapters that subscribe to DOM events
-(e.g. `hashchange`). Injectable for SSR and testing — pass a mock instead of
-the global `window` when the DOM is unavailable.
+The minimal window interface of an adapter that subscribes to a DOM event, for
+example to `hashchange`. You can inject it for SSR and for a test: give a mock in
+place of the global `window` when no DOM is available.
 
-Defined structurally (no `Window` reference) so this package compiles without
-the DOM lib.
+The definition is structural, and it holds no reference to `Window`. This package
+therefore compiles without the DOM lib.
 
 ## Example
 
 ```typescript
-// Normal usage — global window (default)
+// The normal use — the global window, which is the default
 connectRouter({ actor, routeMap });
 
-// SSR / test — injected mock
+// SSR or a test — an injected mock
 const mockWin: WindowLike = { addEventListener: vi.fn(), removeEventListener: vi.fn() };
 connectRouter({ actor, routeMap, window: mockWin });
 ```
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [play-router/src/types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L414)
+Defined in: [play-router/src/types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L413)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [play-router/src/types.ts:414](https://gitlab.com/xmachin-es/xmachin
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [play-router/src/types.ts:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L415)
+Defined in: [play-router/src/types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L414)
 
 #### Parameters
 

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

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

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

@@ -1,12 +1,10 @@
 [API](../../README.md) / @xmachines/play-sveltekit-router
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @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.
 
-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,21 +12,22 @@ 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
 ```
 
-| Peer dependency | Required version  |
-| --------------- | ----------------- |
-| `@sveltejs/kit` | `^2.0.0`          |
-| `svelte`        | `^5.0.0`          |
-| `xstate`        | `^6.0.0-alpha.19` |
+| Peer dependency | Required version |
+| --------------- | ---------------- |
+| `@sveltejs/kit` | `^2.0.0`         |
+| `svelte`        | `^5.0.0`         |
+| `xstate`        | `^5.31.0`        |
 
 ## 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