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

package/api/@xmachines/play-svelte/interfaces/PlayRendererProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRendererProps\<TLogic\>
 
-Defined in: [packages/play-svelte/src/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L13)
+Defined in: [packages/play-svelte/src/types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L13)
 
 ## Type Parameters
 
@@ -12,11 +12,11 @@ Defined in: [packages/play-svelte/src/types.ts:13](https://gitlab.com/xmachin-es
 
 ## Properties
 
-| Property                                   | Type                                                                                                                                                                                                | Description                                                                                                                  | Defined in                                                                                                                                     |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actions"></a> `actions?`   | `object`                                                                                                                                                                                            | -                                                                                                                            | [packages/play-svelte/src/types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L17) |
-| <a id="property-actor"></a> `actor`        | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | -                                                                                                                            | [packages/play-svelte/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L14) |
-| <a id="property-fallback"></a> `fallback?` | `Snippet`\<\[\]\>                                                                                                                                                                                   | Svelte snippet rendered when currentView is null (no active view). Also shown when a catalog component throws during render. | [packages/play-svelte/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L22) |
-| <a id="property-onerror"></a> `onError?`   | (`error`) => `void`                                                                                                                                                                                 | Called when a catalog component throws during render.                                                                        | [packages/play-svelte/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L26) |
-| <a id="property-registry"></a> `registry`  | `ComponentRegistry`                                                                                                                                                                                 | -                                                                                                                            | [packages/play-svelte/src/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L15) |
-| <a id="property-store"></a> `store?`       | `StateStore`                                                                                                                                                                                        | -                                                                                                                            | [packages/play-svelte/src/types.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte/src/types.ts#L16) |
+| Property                                   | Type                                                                                                                                                                                                | Description                                                                                                                                                                                                          | Defined in                                                                                                                                     |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actions"></a> `actions?`   | `object`                                                                                                                                                                                            | -                                                                                                                                                                                                                    | [packages/play-svelte/src/types.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L17) |
+| <a id="property-actor"></a> `actor`        | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | -                                                                                                                                                                                                                    | [packages/play-svelte/src/types.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L14) |
+| <a id="property-fallback"></a> `fallback?` | `Snippet`\<\[\]\>                                                                                                                                                                                   | Svelte snippet rendered when currentView is null (no active view). Also shown when a catalog component throws during render.                                                                                         | [packages/play-svelte/src/types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L22) |
+| <a id="property-onerror"></a> `onError?`   | (`error`, `reset`) => `void`                                                                                                                                                                        | Called when a catalog component throws during render. Receives the thrown error and a `reset` function that clears the boundary and attempts to re-render. Matches Svelte 5's `<svelte:boundary onerror>` signature. | [packages/play-svelte/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L28) |
+| <a id="property-registry"></a> `registry`  | `ComponentRegistry`                                                                                                                                                                                 | -                                                                                                                                                                                                                    | [packages/play-svelte/src/types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L15) |
+| <a id="property-store"></a> `store?`       | `StateStore`                                                                                                                                                                                        | -                                                                                                                                                                                                                    | [packages/play-svelte/src/types.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte/src/types.ts#L16) |

package/api/@xmachines/play-svelte/type-aliases/ComponentFn.md

@@ -6,6 +6,8 @@
 type ComponentFn<C, K> = Component<BaseComponentProps<InferComponentProps<C, K>>>;
 ```
 
+Defined in: `@json-render/svelte`
+
 Component render function type for Svelte
 
 ## Type Parameters

package/api/@xmachines/play-svelte/type-aliases/PlayRenderer.md

@@ -5,3 +5,5 @@
 ```ts
 type PlayRenderer = SvelteComponent;
 ```
+
+Defined in: `svelte`

package/api/@xmachines/play-svelte/variables/PlayRenderer.md

@@ -5,3 +5,5 @@
 ```ts
 const PlayRenderer: LegacyComponentType;
 ```
+
+Defined in: `svelte`

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

@@ -42,6 +42,7 @@ const disconnect = connectRouter({ actor, routeMap });
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
+- [WindowLike](interfaces/WindowLike.md)
 
 ## Type Aliases
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-svelte-spa-router/src/route-map.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/route-map.ts#L3)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -14,7 +14,8 @@ own and inherit the full public API from here.
 - 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
+- Results are cached after the first match in an LRU cache (default 500 entries,
+  configurable via the `cacheSize` constructor option)
 
 **Pattern syntax** (`:param` / `:param?`):
 
@@ -41,19 +42,15 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
-## Extends
-
-- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
-
 ## 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.26/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -63,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
 
@@ -83,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.26/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -106,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()
@@ -118,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.26/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 
@@ -144,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-svelte-spa-router/functions/connectRouter.md

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

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

@@ -6,14 +6,33 @@
 function createRouteMap(machine): RouteMap;
 ```
 
-Defined in: [play-svelte-spa-router/src/create-route-map.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-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.26/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-svelte-spa-router/interfaces/ConnectRouterOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-svelte-spa-router/src/connect-router.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/connect-router.ts#L12)
+Defined in: [play-svelte-spa-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte-spa-router/src/connect-router.ts#L7)
 
 @xmachines/play-svelte-spa-router
 
@@ -10,7 +10,8 @@ Svelte SPA router adapter for XMachines Play architecture.
 
 ## 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-svelte-spa-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/connect-router.ts#L13) |
-| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | [play-svelte-spa-router/src/connect-router.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-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-svelte-spa-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/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.26/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.26/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/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.26/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.26/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.26/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.26/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.26/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.26/packages/play-router/src/types.ts#L224) |

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

@@ -2,11 +2,26 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-svelte-spa-router/src/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/types.ts#L6)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/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     | Defined in                                                                                                                                                |
-| --------------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | [play-svelte-spa-router/src/types.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/types.ts#L8) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | [play-svelte-spa-router/src/types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/types.ts#L7) |
+| 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.26/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.26/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/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.26/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.26/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.26/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

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

@@ -0,0 +1,65 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / WindowLike
+
+# Interface: WindowLike
+
+Defined in: [play-router/src/types.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/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
+the global `window` when the DOM is unavailable.
+
+Defined structurally (no `Window` reference) so this package compiles without
+the DOM lib.
+
+## Example
+
+```typescript
+// Normal usage — global window (default)
+connectRouter({ actor, routeMap });
+
+// SSR / test — injected mock
+const mockWin: WindowLike = { addEventListener: vi.fn(), removeEventListener: vi.fn() };
+connectRouter({ actor, routeMap, window: mockWin });
+```
+
+## Methods
+
+### addEventListener()
+
+```ts
+addEventListener(type, listener): void;
+```
+
+Defined in: [play-router/src/types.ts:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L325)
+
+#### Parameters
+
+| Parameter  | Type                |
+| ---------- | ------------------- |
+| `type`     | `string`            |
+| `listener` | (`event`) => `void` |
+
+#### Returns
+
+`void`
+
+---
+
+### removeEventListener()
+
+```ts
+removeEventListener(type, listener): void;
+```
+
+Defined in: [play-router/src/types.ts:326](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L326)
+
+#### Parameters
+
+| Parameter  | Type                |
+| ---------- | ------------------- |
+| `type`     | `string`            |
+| `listener` | (`event`) => `void` |
+
+#### Returns
+
+`void`

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:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/types.ts#L11)
+Defined in: [play-svelte-spa-router/src/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-svelte-spa-router/src/types.ts#L6)

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.26/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.26/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.26/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.26/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.26/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());
+```