@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

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

@@ -1,23 +1,130 @@
 [Documentation](../../README.md) / @xmachines/play-svelte-spa-router-demo
 
-# @xmachines/play-svelte-spa-router demo
+# Svelte SPA Router Demo
 
-Compact browser demo for the Svelte SPA router adapter.
+Svelte 5 + `svelte-spa-router` integration demo for the XMachines Play architecture using hash-based URL routing.
 
-## Imports
+## What This Demonstrates
 
-- `@xmachines/play-svelte` for the Svelte renderer and registry helpers
-- `@xmachines/play-svelte-spa-router` for hash-based URL ↔ actor sync
+- Shared auth machine reused without framework-specific business logic
+- `connectRouter` hash-URL ↔ actor sync via `@xmachines/play-svelte-spa-router`
+- Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
+- Non-browser invariant tests plus browser E2E coverage
 
-## Commands
+## Running the Demo
+
+From the repository root:
+
+```bash
+npm install
+npm run dev -w packages/play-svelte-spa-router/examples/demo
+```
+
+Then open `http://localhost:5173`.
+
+## Step-by-Step Code Flow
+
+Use this order to understand the implementation:
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanupDemo`.
+2. `src/lib/router.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` synchronizes hash URL changes with the actor via `play.route` events and reflects actor-approved routes back to the hash URL.
+4. `src/App.svelte` imports the singleton `actor` and `registry` from `src/lib/router.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayRenderer>` with the actor and registry and provides the shared UI shell (nav, debug panel).
+6. Browser tests in `test/browser/` validate startup and auth route transitions.
+
+```ts
+// src/lib/router.ts (shape)
+const createDemoPlayer = definePlayer({ machine: authMachine });
+export const actor = createDemoPlayer();
+actor.start();
+
+export const routeMap = createRouteMap(authMachine);
+export const disconnectRouter = connectRouter({ actor, routeMap });
+
+export function cleanupDemo(): void {
+	disconnectRouter();
+	actor.stop();
+}
+```
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<script lang="ts">
+	import Shell from "@xmachines/play-svelte-demo/src/components/Shell.svelte";
+	import { actor, registry } from "./lib/router.js";
+</script>
+
+<Shell {actor} {registry} />
+```
+
+```svelte
+<!-- Shell.svelte — sending events (shape) -->
+<PlayRenderer
+	actor={props.actor}
+	registry={props.registry}
+	actions={{ login: "auth.login", logout: "auth.logout" }}
+/>
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/lib/router.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
+- `src/App.svelte` - minimal root component delegating to shared `Shell.svelte`
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - browser startup and auth route flow coverage
+
+## State Machine & Architecture Details
+
+The demo utilizes XMachines architectural invariants:
+
+1. **Actor Authority:** When a user clicks a nav link, the hash URL changes. `connectRouter` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions to the appropriate state.
+2. **Passive Infrastructure:** `svelte-spa-router` does not execute business logic. The actor dictates whether navigation is permitted. The Svelte application only renders the state.
+3. **Signal-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor signals update, without ad-hoc `$state` stores for business logic.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle used across all `@xmachines` framework adapters:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and project Svelte-local render state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: `cleanupDemo()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+
+## Adapter Boundaries
+
+`connectRouter` (from `@xmachines/play-svelte-spa-router`) is passive infrastructure. It translates hash URL changes into `play.route` events and reflects actor-approved route changes back to the URL. Business validity remains actor-owned. The shared `Shell.svelte` from `@xmachines/play-svelte-demo` is reused to avoid duplicating view components across router demos.
+
+## Available Scripts
+
+These commands are defined in `package.json`:
+
+| Command                                                                 | Description                      |
+| ----------------------------------------------------------------------- | -------------------------------- |
+| `npm run dev -w packages/play-svelte-spa-router/examples/demo`          | Start Vite dev server            |
+| `npm run build -w packages/play-svelte-spa-router/examples/demo`        | Build production bundle          |
+| `npm run preview -w packages/play-svelte-spa-router/examples/demo`      | Preview built bundle             |
+| `npm run test -w packages/play-svelte-spa-router/examples/demo`         | Run Vitest test suite            |
+| `npm run test:browser -w packages/play-svelte-spa-router/examples/demo` | Run browser-focused Vitest suite |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
 
 ```bash
-npm run dev -w @xmachines/play-svelte-spa-router-demo
-npm run build -w @xmachines/play-svelte-spa-router-demo
-npm run test:browser -w @xmachines/play-svelte-spa-router-demo
+npm run test -w packages/play-svelte-spa-router/examples/demo
+npm run test:browser -w packages/play-svelte-spa-router/examples/demo
 ```
 
-## What it proves
+Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
+
+## Learn More
 
-- Clicking a navigation control updates the rendered view
-- Browser back/forward restores the route and view
+- [Svelte SPA Router package README](../play-svelte-spa-router/README.md)
+- [Svelte package README](../play-svelte/README.md)
+- [SvelteKit Router demo README](../play-sveltekit-router-demo/README.md)

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

@@ -8,7 +8,7 @@ Thin SvelteKit adapter for XMachines Play.
 
 - Keeps `actor.currentRoute` and SvelteKit navigation in sync.
 - Exposes a local `RouteMap` plus `createRouteMap(machine)` helper.
-- Stays direct, with no shared `@xmachines/play-svelte-router` abstraction.
+- No intermediate shared package — all shared logic lives in `@xmachines/play-router`.
 - Extracts route params and query values when browser navigation enters through SvelteKit.
 
 ## Usage
@@ -39,6 +39,7 @@ onDestroy(disconnect);
 ## Interfaces
 
 - [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [LocationLike](interfaces/LocationLike.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)

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

@@ -2,23 +2,55 @@
 
 # Class: RouteMap
 
-Defined in: [play-sveltekit-router/src/route-map.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/route-map.ts#L6)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L100)
 
-SvelteKit route map backed by the shared Play router base class.
+Shared bidirectional route map base class.
 
-## Extends
+All framework adapter `RouteMap` classes extend this — they add no logic of their
+own and inherit the full public API from here.
 
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+**Lookup strategy:**
+
+- 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)
+
+**Pattern syntax** (`:param` / `:param?`):
+
+- `:param` — required segment, matches exactly one non-`/` segment
+- `:param?` — optional segment, matches zero or one non-`/` segment
+
+## Example
+
+```typescript
+import { BaseRouteMap } from "@xmachines/play-router";
+
+const map = new BaseRouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+map.getStateIdByPath("/"); // "home"
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/settings"); // "settings"
+map.getStateIdByPath("/unknown"); // null
+
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
 
 ## Constructors
 
 ### Constructor
 
 ```ts
-new RouteMap(mappings): RouteMap;
+new RouteMap(mappings, options?): BaseRouteMap;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:82
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -28,17 +60,15 @@ buckets for efficient candidate selection.
 
 #### Parameters
 
-| Parameter  | Type                                                                     | Description                                                                                                       |
-| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+| 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`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
-`RouteMap`
-
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+`BaseRouteMap`
 
 ## Methods
 
@@ -48,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:112
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -71,10 +101,6 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
-
 ---
 
 ### getStateIdByPath()
@@ -83,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: play-router/dist/base-route-map.d.ts:99
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 
@@ -109,7 +135,3 @@ The mapped state ID, or `null` if no route matches
 map.getStateIdByPath("/profile/123"); // "profile"
 map.getStateIdByPath("/unknown"); // null
 ```
-
-#### Inherited from
-
-[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)

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

@@ -6,7 +6,11 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-sveltekit-router/src/connect-router.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/connect-router.ts#L28)
+Defined in: [play-sveltekit-router/src/connect-router.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-sveltekit-router/src/connect-router.ts#L29)
+
+Connect SvelteKit router to actor.
+
+Returns a cleanup function. The public API surface is unchanged (D-14).
 
 ## Parameters
 
@@ -17,3 +21,12 @@ Defined in: [play-sveltekit-router/src/connect-router.ts:28](https://gitlab.com/
 ## Returns
 
 () => `void`
+
+## Example
+
+```typescript
+import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
+const routeMap = createRouteMap(machine);
+const disconnect = connectRouter({ actor, routeMap });
+onDestroy(() => disconnect());
+```

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

@@ -6,14 +6,33 @@
 function createRouteMap(machine): RouteMap;
 ```
 
-Defined in: [play-sveltekit-router/src/create-route-map.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/create-route-map.ts#L5)
+Defined in: [play-router/src/create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/create-route-map-from-machine.ts#L26)
+
+Create a `BaseRouteMap` 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.
 
 ## Parameters
 
-| Parameter | Type                                                                      |
-| --------- | ------------------------------------------------------------------------- |
-| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+| Parameter | Type                                                                      | Description                                                      |
+| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states. |
 
 ## Returns
 
 [`RouteMap`](../classes/RouteMap.md)
+
+A `BaseRouteMap` for passing to any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMapFromMachine(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
+```

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

@@ -2,11 +2,12 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-sveltekit-router/src/connect-router.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/connect-router.ts#L12)
+Defined in: [play-sveltekit-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-sveltekit-router/src/connect-router.ts#L6)
 
 ## Properties
 
-| Property                                  | Modifier   | Type                                                                                                                                                                                                                                                             | 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-sveltekit-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/connect-router.ts#L13) |
-| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | [play-sveltekit-router/src/connect-router.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/connect-router.ts#L14) |
+| 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-sveltekit-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-sveltekit-router/src/connect-router.ts#L7)   |
+| <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:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-sveltekit-router/src/connect-router.ts#L13) |
+| <a id="property-routemap"></a> `routeMap`  | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-sveltekit-router/src/connect-router.ts#L8)   |

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

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / LocationLike
+
+# Interface: LocationLike
+
+Defined in: [play-router/src/types.ts:344](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L344)
+
+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.
+
+Defined structurally (no `Location` reference) so this package compiles without
+the DOM lib.
+
+## Example
+
+```typescript
+// SSR / test — injected mock
+const mockLoc: LocationLike = { pathname: "/dashboard", search: "?tab=posts" };
+connectRouter({ actor, routeMap, location: mockLoc });
+```
+
+## Properties
+
+| Property                                  | Modifier   | Type     | Defined in                                                                                                                              |
+| ----------------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [play-router/src/types.ts:345](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L345) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L346) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: play-router/dist/types.d.ts:207
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -30,7 +30,7 @@ Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
@@ -85,7 +85,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Merged: path + query
+	params: { section: "profile" }, // Path-only route parameter
 	query: { tab: "security" }, // Query-only
 };
 actor.send(event);
@@ -110,10 +110,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/dist/types.d.ts:212 |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:210 |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | play-router/dist/types.d.ts:211 |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | play-router/dist/types.d.ts:209 |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | play-router/dist/types.d.ts:208 |
+| 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.27/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.27/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.27/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.27/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.27/packages/play-router/src/types.ts#L224) |

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

@@ -2,11 +2,26 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/types.ts#L10)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/base-route-map.ts#L57)
+
+A single state ID ↔ path mapping entry.
+
+Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`BaseRouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
+const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                   | Defined in                                                                                                                                                |
-| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | SvelteKit pathname pattern.                                   | [play-sveltekit-router/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/types.ts#L14) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | XMachines state ID (for example `#home` or `dashboard.home`). | [play-sveltekit-router/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-sveltekit-router/src/types.ts#L12) |
+| 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.27/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.27/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: play-router/dist/types.d.ts:254
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/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/dist/types.d.ts:270
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/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/dist/types.d.ts:285
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

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