@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

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

@@ -0,0 +1,205 @@
+[API](../../README.md) / @xmachines/play-svelte-spa-router
+
+<!-- generated-by: gsd-doc-writer -->
+
+# @xmachines/play-svelte-spa-router
+
+> Svelte SPA Router adapter for the XMachines Play architecture — connects hash-based routing to a `Routable` actor so state machines own navigation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@xmachines/play-svelte-spa-router)](https://www.npmjs.com/package/@xmachines/play-svelte-spa-router)
+
+Part of the [XMachines Play monorepo](../../README.md).
+
+---
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-svelte-spa-router
+```
+
+**Peer dependencies** — install alongside the adapter:
+
+```bash
+pnpm add svelte@^5.0.0 svelte-spa-router@^5.0.0 xstate@^6.0.0-alpha.19
+```
+
+---
+
+## Usage
+
+### 1. Define a routable XState machine
+
+Declare routes in each state's `meta.route` field:
+
+```typescript
+import { setup, types } from "xstate";
+import { createRoutedMachine, playMetaSchema, playRouteEventSchema } from "@xmachines/play-xstate";
+
+const appSetup = setup({
+	schemas: {
+		// params and query are patched into context on every play.route transition
+		context: types<{ params: Record<string, string>; query: Record<string, string> }>(),
+		events: { "play.route": playRouteEventSchema },
+		meta: playMetaSchema,
+	},
+});
+
+// createRoutedMachine(appSetup) has the same signature as appSetup.createMachine
+const machine = createRoutedMachine(appSetup)({
+	id: "app",
+	initial: "home",
+	context: { params: {}, query: {} },
+	states: {
+		home: { id: "home", meta: { route: "/home" } },
+		dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+		settings: { id: "settings", meta: { route: "/settings/:section?" } },
+	},
+});
+```
+
+### 2. Create a player and connect the router
+
+Use `createRouteMap` to build a bidirectional route map from the machine, then call `connectRouter` once — typically in your root Svelte component or a dedicated runtime module:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+
+const createPlayer = definePlayer({ machine });
+export const actor = createPlayer();
+actor.start();
+
+const routeMap = createRouteMap(machine);
+const disconnectRouter = connectRouter({ actor, routeMap });
+```
+
+### 3. Clean up on destroy
+
+Return the cleanup function from `connectRouter` to `onDestroy` (or your lifecycle equivalent):
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from "svelte";
+  import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+
+  const routeMap = createRouteMap(machine);
+  const disconnect = connectRouter({ actor, routeMap });
+
+  onDestroy(() => disconnect());
+</script>
+```
+
+---
+
+## API Summary
+
+### `connectRouter(options): () => void`
+
+Connects `svelte-spa-router` to a `Routable` actor. Returns a cleanup (disconnect) function.
+
+```typescript
+interface ConnectRouterOptions {
+	readonly actor: RoutableActor;
+	readonly routeMap: RouteMap;
+	/**
+	 * Window-like object for `hashchange` subscriptions.
+	 * Defaults to the global `window`. Pass a mock in tests
+	 * or a no-op in SSR environments.
+	 */
+	readonly window?: WindowLike;
+}
+```
+
+**Behaviour:**
+
+- On `connect`: reads the current hash URL via `router.loc.location`, syncs the actor via a `play.route` event, and starts watching for `hashchange` events.
+- On actor `currentRoute` change: calls `push(path)` (svelte-spa-router) to update the URL.
+- On `hashchange`: parses the new location from `router.loc` and sends `play.route` to the actor.
+- On disconnect: removes the `hashchange` listener and unsubscribes from actor signals.
+
+### `createRouteMap(machine): RouteMap`
+
+Re-exported from `@xmachines/play-router`. Extracts all `meta.route` entries from an XState machine and builds a bidirectional route map supporting `URLPattern` matching (including parameterised and optional segments).
+
+### `RouteMap`
+
+Re-exported from `@xmachines/play-router`. Bidirectional map between state IDs and URL paths.
+
+| Method                      | Description                                    |
+| --------------------------- | ---------------------------------------------- |
+| `getStateIdByPath(path)`    | Returns the state ID for a URL path, or `null` |
+| `getPathByStateId(stateId)` | Returns the URL path for a state ID, or `null` |
+
+### Exported types
+
+| Type                   | Description                                                                                               |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `ConnectRouterOptions` | Options accepted by `connectRouter`                                                                       |
+| `RoutableActor`        | Minimal actor interface — `AbstractActor` from `@xmachines/play-actor` combined with the `Routable` mixin |
+| `PlayRouteEvent`       | The `play.route` event type sent to the actor                                                             |
+| `RouterBridge`         | Interface that all router bridges must satisfy                                                            |
+| `RouteMapping`         | Route-entry shape within a `RouteMap`                                                                     |
+| `RouteMapOptions`      | Options for `createRouteMap`                                                                              |
+| `WindowLike`           | Minimal `window` interface for testability                                                                |
+
+---
+
+## How it works
+
+`SvelteSpaRouterBridge` extends `RouterBridgeBase` from `@xmachines/play-router` and implements three abstract methods:
+
+| Method                   | svelte-spa-router equivalent               |
+| ------------------------ | ------------------------------------------ |
+| `navigateRouter(path)`   | `push(path)`                               |
+| `watchRouterChanges()`   | `win.addEventListener("hashchange", …)`    |
+| `unwatchRouterChanges()` | `win.removeEventListener("hashchange", …)` |
+
+Initial path is read from `router.loc.location` and initial search from `router.loc.querystring`. Restore-vs-deeplink detection, guard-redirect flows, and `isProcessingNavigation` debouncing are inherited from `RouterBridgeBase`.
+
+---
+
+## Testing
+
+Run the package tests in isolation:
+
+```bash
+pnpm --filter @xmachines/play-svelte-spa-router test
+```
+
+Or from inside this package directory:
+
+```bash
+pnpm test
+```
+
+Coverage thresholds: **80%** lines / functions / branches / statements.
+
+---
+
+## License
+
+MIT © XMachines Contributors. See [LICENSE](./LICENSE).
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+
+## Interfaces
+
+- [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouterBridge](interfaces/RouterBridge.md)
+- [WindowLike](interfaces/WindowLike.md)
+
+## Type Aliases
+
+- [RoutableActor](type-aliases/RoutableActor.md)
+
+## Functions
+
+- [connectRouter](functions/connectRouter.md)
+- [createRouteMap](functions/createRouteMap.md)

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

@@ -0,0 +1,149 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/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-svelte-spa-router/functions/connectRouter.md

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / connectRouter
+
+# Function: connectRouter()
+
+```ts
+function connectRouter(options): () => void;
+```
+
+Defined in: [play-svelte-spa-router/src/connect-router.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-svelte-spa-router/src/connect-router.ts#L29)
+
+Connect svelte-spa-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-svelte-spa-router";
+const routeMap = createRouteMap(machine);
+const disconnect = connectRouter({ actor, routeMap });
+onDestroy(() => disconnect());
+```

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

@@ -0,0 +1,39 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-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/v2.0.0-alpha.1/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 v6 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-svelte-spa-router/interfaces/ConnectRouterOptions.md

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / ConnectRouterOptions
+
+# Interface: ConnectRouterOptions
+
+Defined in: [play-svelte-spa-router/src/connect-router.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-svelte-spa-router/src/connect-router.ts#L5)
+
+@xmachines/play-svelte-spa-router
+
+Svelte SPA router adapter for XMachines Play architecture.
+
+## Properties
+
+| Property                                  | Modifier   | Type                                                                 | Description                                                                                                                                                                                                     | Defined in                                                                                                                                                                    |
+| ----------------------------------------- | ---------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `readonly` | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | -                                                                                                                                                                                                               | [play-svelte-spa-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-svelte-spa-router/src/connect-router.ts#L6)   |
+| <a id="property-routemap"></a> `routeMap` | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                 | -                                                                                                                                                                                                               | [play-svelte-spa-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-svelte-spa-router/src/connect-router.ts#L7)   |
+| <a id="property-window"></a> `window?`    | `readonly` | [`WindowLike`](WindowLike.md)                                        | Window-like object for `hashchange` subscriptions. Defaults to the global `window` when one exists; in environments without a window (SSR/Node) the `hashchange` subscription is skipped. Pass a mock in tests. | [play-svelte-spa-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-svelte-spa-router/src/connect-router.ts#L13) |

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

@@ -0,0 +1,129 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: [play-router/src/types.ts:244](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L244)
+
+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:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L249) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:247](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L247) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L248) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:246](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L246) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:245](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L245) |

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

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouteMapOptions
+
+# Interface: RouteMapOptions
+
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/create-route-map.ts#L9)
+
+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/v2.0.0-alpha.1/packages/play-router/src/create-route-map.ts#L20) |

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

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouteMapping
+
+# Interface: RouteMapping
+
+Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L51)
+
+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/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L55) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L53) |