@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

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

@@ -1,41 +1,180 @@
 [API](../../README.md) / @xmachines/play-svelte-spa-router
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-svelte-spa-router
 
-Svelte SPA adapter for XMachines Play.
+> Svelte SPA Router adapter for the XMachines Play architecture — connects hash-based routing to a `Routable` actor so state machines own navigation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@xmachines/play-svelte-spa-router)](https://www.npmjs.com/package/@xmachines/play-svelte-spa-router)
+
+Part of the [XMachines Play monorepo](../../README.md).
+
+---
 
-This package keeps a Play actor's route state aligned with `svelte-spa-router` hash navigation. It is a direct adapter, not a shared router-core layer.
+## Installation
+
+```bash
+npm install @xmachines/play-svelte-spa-router
+```
 
-## Install
+**Peer dependencies** — install alongside the adapter:
 
 ```bash
-npm install @xmachines/play-svelte-spa-router svelte svelte-spa-router
+npm install svelte@^5.46.4 svelte-spa-router@^5.0.1 xstate@^5.30.0
 ```
 
-## Quick start
+---
+
+## Usage
+
+### 1. Define a routable XState machine
+
+Declare routes in each state's `meta.route` field:
+
+```typescript
+import { setup } from "xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import type { PlayRouteEvent } from "@xmachines/play-svelte-spa-router";
+
+const machine = setup({
+	types: { events: {} as PlayRouteEvent },
+}).createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { meta: { route: "/home" } },
+			dashboard: { meta: { route: "/dashboard" } },
+			settings: { meta: { route: "/settings/:section?" } },
+		},
+	}),
+);
+```
 
-```ts
+### 2. Create a player and connect the router
+
+Use `createRouteMap` to build a bidirectional route map from the machine, then call `connectRouter` once — typically in your root Svelte component or a dedicated runtime module:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
 import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
 
+const createPlayer = definePlayer({ machine });
+export const actor = createPlayer();
+actor.start();
+
 const routeMap = createRouteMap(machine);
-const disconnect = connectRouter({ actor, routeMap });
+const disconnectRouter = connectRouter({ actor, routeMap });
+```
+
+### 3. Clean up on destroy
+
+Return the cleanup function from `connectRouter` to `onDestroy` (or your lifecycle equivalent):
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from "svelte";
+  import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+
+  const routeMap = createRouteMap(machine);
+  const disconnect = connectRouter({ actor, routeMap });
+
+  onDestroy(() => disconnect());
+</script>
+```
+
+---
+
+## API Summary
+
+### `connectRouter(options): () => void`
+
+Connects `svelte-spa-router` to a `Routable` actor. Returns a cleanup (disconnect) function.
+
+```typescript
+interface ConnectRouterOptions {
+	readonly actor: AbstractActor<AnyActorLogic> & Routable;
+	readonly routeMap: RouteMap;
+	/**
+	 * Window-like object for `hashchange` subscriptions.
+	 * Defaults to the global `window`. Pass a mock in tests
+	 * or a no-op in SSR environments.
+	 */
+	readonly window?: WindowLike;
+}
 ```
 
-## API
+**Behaviour:**
+
+- On `connect`: reads the current hash URL via `router.loc`, syncs the actor via a `play.route` event, and starts watching for `hashchange` events.
+- On actor `currentRoute` change: calls `push(path)` (svelte-spa-router) to update the URL.
+- On `hashchange`: parses the new location from `router.loc` and sends `play.route` to the actor.
+- On disconnect: removes the `hashchange` listener and unsubscribes from actor signals.
+
+### `createRouteMap(machine): RouteMap`
+
+Re-exported from `@xmachines/play-router`. Extracts all `meta.route` entries from an XState machine and builds a bidirectional route map supporting `URLPattern` matching (including parameterised and optional segments).
+
+### `RouteMap`
+
+Re-exported from `@xmachines/play-router`. Bidirectional map between state IDs and URL paths.
+
+| Method                      | Description                                    |
+| --------------------------- | ---------------------------------------------- |
+| `getStateIdByPath(path)`    | Returns the state ID for a URL path, or `null` |
+| `getPathByStateId(stateId)` | Returns the URL path for a state ID, or `null` |
+
+### Exported types
+
+| Type                   | Description                                    |
+| ---------------------- | ---------------------------------------------- |
+| `ConnectRouterOptions` | Options accepted by `connectRouter`            |
+| `RoutableActor`        | `AbstractActor & Routable` convenience alias   |
+| `PlayRouteEvent`       | The `play.route` event type sent to the actor  |
+| `RouterBridge`         | Interface that all router bridges must satisfy |
+| `RouteMapping`         | Route-entry shape within a `RouteMap`          |
+| `RouteMapOptions`      | Options for `createRouteMap`                   |
+| `WindowLike`           | Minimal `window` interface for testability     |
+
+---
+
+## How it works
 
-- `createRouteMap(machine)` builds the adapter's `RouteMap` from Play route metadata.
-- `connectRouter({ actor, routeMap })` syncs hash navigation with `actor.currentRoute`.
+`SvelteSpaRouterBridge` extends `RouterBridgeBase` from `@xmachines/play-router` and implements three abstract methods:
+
+| Method                   | svelte-spa-router equivalent               |
+| ------------------------ | ------------------------------------------ |
+| `navigateRouter(path)`   | `push(path)`                               |
+| `watchRouterChanges()`   | `win.addEventListener("hashchange", …)`    |
+| `unwatchRouterChanges()` | `win.removeEventListener("hashchange", …)` |
+
+Initial path and search are read from `router.loc.location` and `router.loc.querystring`. Restore-vs-deeplink detection, guard-redirect flows, and `isProcessingNavigation` debouncing are inherited from `RouterBridgeBase`.
+
+---
+
+## Testing
+
+Run the package tests in isolation:
+
+```bash
+npm test -w @xmachines/play-svelte-spa-router
+```
+
+Or from inside this package directory:
+
+```bash
+npm test
+```
 
-## Notes
+Coverage thresholds: **80%** lines / functions / branches / statements.
 
-- Hash changes are handled locally in this package.
-- The adapter uses the shared Play router helpers for route resolution and event formatting.
-- Actor routes may be either state IDs or resolved paths; the adapter normalizes both before pushing hash navigation.
+---
 
-## Learn More
+## License
 
-- [Demo](../../../examples/@xmachines/play-svelte-spa-router-demo/README.md)
-- [Svelte renderer](../play-svelte/README.md)
+MIT © XMachines Contributors. See [LICENSE](./LICENSE).
 
 ## Classes
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -50,7 +50,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -109,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -6,7 +6,7 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-svelte-spa-router/src/connect-router.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte-spa-router/src/connect-router.ts#L30)
+Defined in: [play-svelte-spa-router/src/connect-router.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-svelte-spa-router/src/connect-router.ts#L30)
 
 Connect svelte-spa-router to actor.
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

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

@@ -2,7 +2,7 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-svelte-spa-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte-spa-router/src/connect-router.ts#L7)
+Defined in: [play-svelte-spa-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-svelte-spa-router/src/connect-router.ts#L7)
 
 @xmachines/play-svelte-spa-router
 
@@ -12,6 +12,6 @@ Svelte SPA router adapter for XMachines Play architecture.
 
 | Property                                  | Modifier   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                              | Defined in                                                                                                                                                                    |
 | ----------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `readonly` | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | -                                                                                                                                        | [play-svelte-spa-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte-spa-router/src/connect-router.ts#L8)   |
-| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | -                                                                                                                                        | [play-svelte-spa-router/src/connect-router.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte-spa-router/src/connect-router.ts#L9)   |
-| <a id="property-window"></a> `window?`    | `readonly` | [`WindowLike`](WindowLike.md)                                                                                                                                                                                                                                    | Window-like object for `hashchange` subscriptions. Defaults to the global `window`. Pass a mock in tests or a no-op in SSR environments. | [play-svelte-spa-router/src/connect-router.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-svelte-spa-router/src/connect-router.ts#L14) |
+| <a id="property-actor"></a> `actor`       | `readonly` | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | -                                                                                                                                        | [play-svelte-spa-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-svelte-spa-router/src/connect-router.ts#L8)   |
+| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | -                                                                                                                                        | [play-svelte-spa-router/src/connect-router.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-svelte-spa-router/src/connect-router.ts#L9)   |
+| <a id="property-window"></a> `window?`    | `readonly` | [`WindowLike`](WindowLike.md)                                                                                                                                                                                                                                    | Window-like object for `hashchange` subscriptions. Defaults to the global `window`. Pass a mock in tests or a no-op in SSR environments. | [play-svelte-spa-router/src/connect-router.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-svelte-spa-router/src/connect-router.ts#L14) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L223)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L228) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L226) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L227) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L225) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L224) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L224) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/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/v1.0.0-beta.48/packages/play-router/src/create-route-map.ts#L9)
 
 Options for `createRouteMap` and `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ Options for `createRouteMap` and `createRouteMapFromTree`.
 
 | 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/v1.0.0-beta.46/packages/play-router/src/create-route-map.ts#L20) |
+| <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/v1.0.0-beta.48/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L57)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L57)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | 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:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L61) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/base-route-map.ts#L59) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L271)
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L287)
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L303)
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

@@ -2,7 +2,7 @@
 
 # Interface: WindowLike
 
-Defined in: [play-router/src/types.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L324)
+Defined in: [play-router/src/types.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L324)
 
 Minimal window interface required by adapters that subscribe to DOM events
 (e.g. `hashchange`). Injectable for SSR and testing — pass a mock instead of
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [play-router/src/types.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L325)
+Defined in: [play-router/src/types.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L325)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [play-router/src/types.ts:325](https://gitlab.com/xmachin-es/xmachin
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [play-router/src/types.ts:326](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L326)
+Defined in: [play-router/src/types.ts:326](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L326)
 
 #### 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/v1.0.0-beta.46/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/v1.0.0-beta.48/packages/play-svelte-spa-router/src/types.ts#L6)

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

@@ -1,41 +1,192 @@
 [API](../../README.md) / @xmachines/play-sveltekit-router
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-sveltekit-router
 
-Thin SvelteKit adapter for XMachines Play.
+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`.
+
+Part of the [xmachines-js monorepo](../../README.md).
+
+## Installation
+
+```bash
+npm install @xmachines/play-sveltekit-router
+```
+
+**Peer dependencies** (must be installed separately):
+
+```bash
+npm install @sveltejs/kit svelte xstate
+```
+
+| Peer dependency | Required version |
+| --------------- | ---------------- |
+| `@sveltejs/kit` | `^2.16.0`        |
+| `svelte`        | `^5.46.4`        |
+| `xstate`        | `^5.30.0`        |
+
+## Quick Start
+
+```typescript
+import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
+import { definePlayer } from "@xmachines/play-xstate";
+import { myMachine } from "./machine.js";
+
+// 1. Create the actor
+const createPlayer = definePlayer({ machine: myMachine });
+const actor = createPlayer();
+actor.start();
+
+// 2. Build a bidirectional route map from the machine definition
+const routeMap = createRouteMap(myMachine);
 
-## What it does
+// 3. Connect the router — returns a cleanup function
+const disconnect = connectRouter({ actor, routeMap });
+
+// 4. Clean up when the component is destroyed
+onDestroy(() => disconnect());
+```
+
+The bridge synchronises in both directions:
 
-- Keeps `actor.currentRoute` and SvelteKit navigation in sync.
-- Exposes a local `RouteMap` plus `createRouteMap(machine)` helper.
-- No intermediate shared package — all shared logic lives in.
-- Extracts route params and query values when browser navigation enters through SvelteKit.
+- **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()`.
 
 ## Usage
 
-```ts
+### `connectRouter(options)` — high-level API
+
+The primary integration point. Instantiates a `SvelteKitRouterBridge`, calls `connect()`, and returns a cleanup function.
+
+```typescript
 import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
 
 const routeMap = createRouteMap(machine);
+
+// In a Svelte component or SvelteKit layout
 const disconnect = connectRouter({ actor, routeMap });
 
-onDestroy(disconnect);
+// Pass an explicit location for SSR or test environments
+const disconnect = connectRouter({
+	actor,
+	routeMap,
+	location: { pathname: "/dashboard", search: "?tab=stats" },
+});
+
+// Cleanup
+onDestroy(() => disconnect());
 ```
 
-## Notes
+**`ConnectRouterOptions`:**
+
+| Property   | Type                                      | Required | Description                                                                                                                 |
+| ---------- | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `actor`    | `AbstractActor<AnyActorLogic> & Routable` | 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. |
+
+### `SvelteKitRouterBridge` — low-level class
+
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Use directly when you need fine-grained control over the connection lifecycle.
 
-- `connectRouter()` returns a cleanup function. Call it during teardown to stop syncing actor updates.
-- Actor routes may be either state IDs or resolved paths; the adapter normalizes both.
-- Incoming SvelteKit paths are converted into `play.route` events with extracted `params` and `query`.
+```typescript
+import { SvelteKitRouterBridge, createRouteMap } from "@xmachines/play-sveltekit-router";
 
-## Route map
+const routeMap = createRouteMap(machine);
+const bridge = new SvelteKitRouterBridge(actor, routeMap, location);
+bridge.connect();
+
+// On teardown
+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`)
+
+### `createRouteMap(machine)`
+
+Factory that builds a `RouteMap` from an XState machine definition. State route patterns are read from `state.meta.route`.
+
+```typescript
+import { createRouteMap } from "@xmachines/play-sveltekit-router";
+import { createMachine } from "xstate";
+
+const machine = createMachine({
+	id: "app",
+	initial: "home",
+	states: {
+		home: { meta: { route: "/home" } },
+		dashboard: { meta: { route: "/dashboard" } },
+		settings: { meta: { route: "/settings/:section?" } },
+	},
+});
+
+const routeMap = createRouteMap(machine);
+```
+
+### `RouteMap` / `RouteMapping`
+
+Bidirectional state ID ↔ URL path mapping. Re-exported from `@xmachines/play-router`.
+
+```typescript
+import { RouteMap } from "@xmachines/play-sveltekit-router";
+
+const routeMap = new RouteMap([
+	{ stateId: "#app.home", path: "/home" },
+	{ stateId: "#app.dashboard", path: "/dashboard" },
+	{ stateId: "#app.settings", path: "/settings/:section?" },
+]);
+```
+
+## API Summary
+
+### 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     | `AbstractActor<AnyActorLogic> & Routable` — minimum actor shape accepted by the bridge     |
+
+## 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:
+
+```bash
+npm install
+npm run dev -w @xmachines/play-sveltekit-router-demo
+```
+
+Then open `http://localhost:5173`.
+
+## Testing
+
+Run tests for this package in isolation:
+
+```bash
+# From the monorepo root
+npm test -w packages/play-sveltekit-router
+
+# Or from this package directory
+npm test
+```
 
-`createRouteMap(machine)` reads route metadata from the machine and builds a Play route map for SvelteKit paths.
+Coverage thresholds: **80%** lines, functions, branches, and statements.
 
-## Learn More
+## License
 
-- [Demo](../../../examples/@xmachines/play-sveltekit-router-demo/README.md)
-- [Svelte renderer](../play-svelte/README.md)
+MIT — see [LICENSE](LICENSE).
 
 ## Classes