@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,211 @@
+[API](../../README.md) / @xmachines/play-sveltekit-router
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-sveltekit-router
+
+SvelteKit router adapter for the XMachines Universal Player Architecture. Provides bidirectional synchronisation between a `RoutableActor`'s state machine routes and the browser URL via SvelteKit's `$app/navigation`.
+
+Part of the [xmachines-js monorepo](../../README.md).
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-sveltekit-router
+```
+
+**Peer dependencies** (must be installed separately):
+
+```bash
+pnpm add @sveltejs/kit svelte xstate
+```
+
+| Peer dependency | Required version |
+| --------------- | ---------------- |
+| `@sveltejs/kit` | `^2.0.0`         |
+| `svelte`        | `^5.0.0`         |
+| `xstate`        | `^5.31.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);
+
+// 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:
+
+- **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
+
+### `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 });
+
+// Pass an explicit location for SSR or test environments
+const disconnect = connectRouter({
+	actor,
+	routeMap,
+	location: { pathname: "/dashboard", search: "?tab=stats" },
+});
+
+// Cleanup
+onDestroy(() => disconnect());
+```
+
+**`ConnectRouterOptions`:**
+
+| Property   | Type                   | Required | Description                                                                                                                 |
+| ---------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `actor`    | `RoutableActor`        | Yes      | The XMachines actor to synchronise with the router                                                                          |
+| `routeMap` | `RouteMap`             | Yes      | Bidirectional state ID ↔ URL path mapping                                                                                   |
+| `location` | `LocationLike \| null` | No       | Location stub for initial URL reads. Defaults to `globalThis.location`. Pass a mock in tests or a stub in SSR environments. |
+
+### `SvelteKitRouterBridge` — low-level class
+
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Use directly when you need fine-grained control over the connection lifecycle.
+
+```typescript
+import { SvelteKitRouterBridge, createRouteMap } from "@xmachines/play-sveltekit-router";
+
+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     | Minimal actor interface from `@xmachines/play-router` — `currentRoute`, `initialRoute`, `send(PlayRouteEvent)` |
+
+## Demo
+
+A runnable Svelte 5 + SvelteKit router adapter demo is available in [`examples/demo/`](../../../examples/@xmachines/play-sveltekit-router-demo/README.md). To run it from the monorepo root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-sveltekit-router-demo run dev
+```
+
+Then open `http://localhost:5173`.
+
+## Testing
+
+Run tests for this package in isolation:
+
+```bash
+# From the monorepo root
+pnpm --filter @xmachines/play-sveltekit-router test
+
+# Or from this package directory
+pnpm test
+```
+
+Coverage thresholds: **80%** lines, functions, branches, and statements.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+
+## Interfaces
+
+- [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [LocationLike](interfaces/LocationLike.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouterBridge](interfaces/RouterBridge.md)
+
+## Type Aliases
+
+- [RoutableActor](type-aliases/RoutableActor.md)
+
+## Functions
+
+- [connectRouter](functions/connectRouter.md)
+- [createRouteMap](functions/createRouteMap.md)

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

@@ -0,0 +1,149 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L101)
+
+Shared bidirectional route map base class.
+
+All framework adapters use this class as their route map — they add no logic of their
+own and inherit the full public API from here.
+
+**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
+- `*` — wildcard, matches any number of segments (URLPattern semantics)
+
+**StateId forms:** stateIds may be registered and looked up in either
+`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+`getStateIdByPath` returns the stateId exactly as registered;
+`getPathByStateId` accepts both forms. Registering the same stateId in both
+forms refers to one entry (the later registration wins for reverse lookup).
+
+## Example
+
+```typescript
+import { RouteMap } from "@xmachines/play-router";
+
+const map = new RouteMap([
+	{ 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, options?): RouteMap;
+```
+
+Defined in: [play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L127)
+
+Build a route map from an array of state ID ↔ path mappings.
+
+Static paths (no `:param`) are indexed in an O(1) `Map`.
+Parameterized paths are compiled to `URLPattern` and grouped into first-segment
+buckets for efficient candidate selection.
+
+#### Parameters
+
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint). |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+#### Returns
+
+`RouteMap`
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+Defined in: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L218)
+
+Look up the path pattern registered for a state ID.
+
+Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+which form was used at registration — lookups are canonicalized internally,
+so consumers never need to try both forms.
+
+#### Parameters
+
+| Parameter | Type     | Description                                               |
+| --------- | -------- | --------------------------------------------------------- |
+| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The registered path pattern, or `null` if the state ID is unknown
+
+#### Example
+
+```typescript
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
+map.getPathByStateId("missing"); // null
+```
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+Defined in: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L178)
+
+Resolve a URL path to its mapped state ID.
+
+Strips query strings and hash fragments before matching. Tries an O(1) exact
+lookup first, then falls back to bucket-indexed pattern matching. Results are
+cached after the first pattern match.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------ |
+| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The mapped state ID, or `null` if no route matches
+
+#### Example
+
+```typescript
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/unknown"); // null
+```

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

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / connectRouter
+
+# Function: connectRouter()
+
+```ts
+function connectRouter(options): () => void;
+```
+
+Defined in: [play-sveltekit-router/src/connect-router.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-sveltekit-router/src/connect-router.ts#L27)
+
+Connect SvelteKit router to actor.
+
+Returns a cleanup function. The public API surface is unchanged (D-14).
+
+## Parameters
+
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `options` | [`ConnectRouterOptions`](../interfaces/ConnectRouterOptions.md) |
+
+## 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

@@ -0,0 +1,39 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+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/packages/play-router/src/create-route-map.ts#L45)
+
+Create a `RouteMap` from an XState state machine.
+
+Extracts all routable states (those with `meta.route`) and builds a bidirectional
+path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
+subclasses to translate browser URL changes into `play.route` actor events and
+vice-versa.
+
+## Parameters
+
+| Parameter  | Type                                                                      | Description                                                                                                         |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
+
+## Returns
+
+[`RouteMap`](../classes/RouteMap.md)
+
+A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+import { createRouteMap } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMap(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
+```

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

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

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

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / LocationLike
+
+# Interface: LocationLike
+
+Defined in: [play-router/src/types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L414)
+
+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:415](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L415) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:416](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L416) |

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

@@ -0,0 +1,129 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L225)
+
+Enhanced routing event with parameter and query support
+
+Unified routing event used throughout the Play architecture. Supports parameter-aware
+navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
+user navigation intent that the Actor evaluates through guards. Infrastructure proposes
+via `play.route` events, Actor decides via state machine transitions.
+
+**Browser Navigation Flow:**
+
+1. Browser fires `popstate`
+2. Router adapter resolves URL to route target
+3. Adapter sends `PlayRouteEvent` to Actor
+4. Actor validates transition via state machine guards
+
+## Param
+
+**type**
+
+Event discriminator (always "play.route")
+
+## Param
+
+**to**
+
+Target state ID with # prefix (e.g., '#home', '#profile')
+
+## Param
+
+**params**
+
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+
+## Param
+
+**query**
+
+Query parameters only (isolated from path params)
+
+## Param
+
+**match**
+
+Full URLPattern match result for debugging/observability (optional)
+
+## Examples
+
+Combining base and routing events
+
+```typescript
+import type { PlayEvent } from "@xmachines/play";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+type AppEvent = PlayEvent | PlayRouteEvent;
+```
+
+Basic navigation to a route
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#home",
+};
+actor.send(event);
+```
+
+Navigation with route parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#profile",
+	params: { userId: "123" },
+};
+actor.send(event);
+// Resolves to route: /profile/123
+```
+
+Navigation with query parameters
+
+```typescript
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const event: PlayRouteEvent = {
+	type: "play.route",
+	to: "#settings",
+	params: { section: "profile" }, // Path-only route parameter
+	query: { tab: "security" }, // Query-only
+};
+actor.send(event);
+// Resolves to route: /settings/profile?tab=security
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.md)
+
+## Remarks
+
+Use `play.route` when you need parameter-aware navigation with the `route: {}`
+config pattern on your state machine nodes. The `match` field exposes the full
+URLPatternResult for advanced use cases (debugging, pattern analysis).
+
+## Indexable
+
+```ts
+[key: string]: unknown
+```
+
+## Properties
+
+| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/types.ts#L226) |

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

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RouteMapOptions
+
+# Interface: RouteMapOptions
+
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/create-route-map.ts#L9)
+
+Options for `createRouteMap` and `createRouteMapFromTree`.
+
+## Properties
+
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-sveltekit-router](../README.md) / RouteMapping
+
+# Interface: RouteMapping
+
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L51)
+
+A single state ID ↔ path mapping entry.
+
+Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
+Adapter packages re-export a structurally compatible `RouteMapping` type under
+their own name. This type is published from `@xmachines/play-router` as
+`RouteMapping` to avoid name collisions with those adapter-local types.
+
+## Example
+
+```typescript
+const mapping: RouteMapping = { stateId: "home", path: "/" };
+const paramMapping: RouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
+
+## Properties
+
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-router/src/base-route-map.ts#L53) |