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

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

@@ -0,0 +1,22 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / PlayRendererProps
+
+# 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)
+
+## Type Parameters
+
+| Type Parameter                                                                           | Default type                                                          |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) |
+
+## 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) |

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

@@ -0,0 +1,16 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / ComponentFn
+
+# Type Alias: ComponentFn\<C, K\>
+
+```ts
+type ComponentFn<C, K> = Component<BaseComponentProps<InferComponentProps<C, K>>>;
+```
+
+Component render function type for Svelte
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |

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

@@ -0,0 +1,7 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / PlayRenderer
+
+# Type Alias: PlayRenderer
+
+```ts
+type PlayRenderer = SvelteComponent;
+```

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

@@ -0,0 +1,7 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / PlayRenderer
+
+# Variable: PlayRenderer
+
+```ts
+const PlayRenderer: LegacyComponentType;
+```

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

@@ -0,0 +1,7 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / getBoundProp
+
+# Variable: getBoundProp
+
+```ts
+getBoundProp: any;
+```

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

@@ -0,0 +1,53 @@
+[Documentation](../../README.md) / @xmachines/play-svelte-spa-router
+
+# @xmachines/play-svelte-spa-router
+
+Svelte SPA adapter for XMachines Play.
+
+This package keeps a Play actor's route state aligned with `svelte-spa-router` hash navigation. It is a direct adapter, not a shared router-core layer.
+
+## Install
+
+```bash
+npm install @xmachines/play-svelte-spa-router svelte svelte-spa-router
+```
+
+## Quick start
+
+```ts
+import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+
+const routeMap = createRouteMap(machine);
+const disconnect = connectRouter({ actor, routeMap });
+```
+
+## API
+
+- `createRouteMap(machine)` builds the adapter's `RouteMap` from Play route metadata.
+- `connectRouter({ actor, routeMap })` syncs hash navigation with `actor.currentRoute`.
+
+## Notes
+
+- Hash changes are handled locally in this package.
+- The adapter uses the shared Play router helpers for route resolution and event formatting.
+- Actor routes may be either state IDs or resolved paths; the adapter normalizes both before pushing hash navigation.
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+
+## Interfaces
+
+- [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.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-svelte-spa-router/classes/RouteMap.md

@@ -0,0 +1,150 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouteMap
+
+# 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)
+
+Shared bidirectional route map base class.
+
+All framework adapter `RouteMap` classes extend this — 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
+
+**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
+```
+
+## Extends
+
+- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new RouteMap(mappings): RouteMap;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:82
+
+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` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+
+#### Returns
+
+`RouteMap`
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:112
+
+Look up the path pattern registered for a state ID.
+
+#### 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("missing"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+Defined in: play-router/dist/base-route-map.d.ts:99
+
+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
+```
+
+#### 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

@@ -0,0 +1,19 @@
+[Documentation](../../../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:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-svelte-spa-router/src/connect-router.ts#L46)
+
+## Parameters
+
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `options` | [`ConnectRouterOptions`](../interfaces/ConnectRouterOptions.md) |
+
+## Returns
+
+() => `void`

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

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+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)
+
+## Parameters
+
+| Parameter | Type                                                                      |
+| --------- | ------------------------------------------------------------------------- |
+| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
+
+## Returns
+
+[`RouteMap`](../classes/RouteMap.md)

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

@@ -0,0 +1,16 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / ConnectRouterOptions
+
+# 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)
+
+@xmachines/play-svelte-spa-router
+
+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) |

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

@@ -0,0 +1,119 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+Defined in: play-router/dist/types.d.ts:207
+
+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
+
+Event discriminator (always "play.route")
+
+## Param
+
+Target state ID with # prefix (e.g., '#home', '#profile')
+
+## Param
+
+Merged path + query parameters (path parameters win conflicts)
+
+## Param
+
+Query parameters only (isolated from path params)
+
+## Param
+
+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" }, // Merged: path + query
+	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/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 |

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

@@ -0,0 +1,12 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouteMapping
+
+# 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)
+
+## 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) |

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

@@ -0,0 +1,104 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouterBridge
+
+# Interface: RouterBridge
+
+Defined in: play-router/dist/types.d.ts:254
+
+RouterBridge interface for runtime infrastructure adapters
+
+Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and
+the Actor. Infrastructure "bridges" to the Actor by observing its signals and
+managing its own lifecycle accordingly.
+
+**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
+a unidirectional observation pattern. Infrastructure connects to observe Actor signals
+(currentRoute, currentView, state) and reflects changes without making state decisions.
+
+## Example
+
+TanStack Router bridge implementation
+
+```typescript
+import type { RouterBridge } from "@xmachines/play-router";
+import { Signal } from "@xmachines/play-signals";
+
+class TanStackRouterBridge implements RouterBridge {
+	private watcher: Signal.Watcher | null = null;
+
+	async connect(): Promise<void> {
+		// Start observing actor.currentRoute signal
+		this.watcher = new Signal.subtle.Watcher(() => {
+			const route = actor.currentRoute.get();
+			if (route) router.navigate(route);
+		});
+		this.watcher.watch(actor.currentRoute);
+	}
+
+	async disconnect(): Promise<void> {
+		// Stop observing, cleanup watchers
+		this.watcher?.unwatch(actor.currentRoute);
+		this.watcher = null;
+	}
+}
+```
+
+## See
+
+[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void | Promise<void>;
+```
+
+Defined in: play-router/dist/types.d.ts:270
+
+Connect the router bridge to the Actor
+
+Called when Infrastructure should begin observing Actor signals and
+synchronizing its state (e.g., browser URL) with Actor state.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when connection is established, or void for synchronous connection
+
+#### Example
+
+```typescript
+const bridge: RouterBridge = createBridge(actor, router);
+await bridge.connect();
+// Bridge now observing actor.currentRoute signal
+```
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void | Promise<void>;
+```
+
+Defined in: play-router/dist/types.d.ts:285
+
+Disconnect the router bridge from the Actor
+
+Called when Infrastructure should stop observing and clean up resources
+(e.g., signal watchers, event listeners).
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+Promise that resolves when disconnection is complete, or void for synchronous disconnection
+
+#### Example
+
+```typescript
+await bridge.disconnect();
+// Bridge stopped observing, resources cleaned up
+```

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

@@ -0,0 +1,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RoutableActor
+
+# Type Alias: RoutableActor
+
+```ts
+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)

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

@@ -0,0 +1,23 @@
+[Documentation](../../README.md) / @xmachines/play-svelte-spa-router-demo
+
+# @xmachines/play-svelte-spa-router demo
+
+Compact browser demo for the Svelte SPA router adapter.
+
+## Imports
+
+- `@xmachines/play-svelte` for the Svelte renderer and registry helpers
+- `@xmachines/play-svelte-spa-router` for hash-based URL ↔ actor sync
+
+## Commands
+
+```bash
+npm run dev -w @xmachines/play-svelte-spa-router-demo
+npm run build -w @xmachines/play-svelte-spa-router-demo
+npm run test:browser -w @xmachines/play-svelte-spa-router-demo
+```
+
+## What it proves
+
+- Clicking a navigation control updates the rendered view
+- Browser back/forward restores the route and view

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

@@ -0,0 +1,53 @@
+[Documentation](../../README.md) / @xmachines/play-sveltekit-router
+
+# @xmachines/play-sveltekit-router
+
+Thin SvelteKit adapter for XMachines Play.
+
+## What it does
+
+- 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.
+- Extracts route params and query values when browser navigation enters through SvelteKit.
+
+## Usage
+
+```ts
+import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
+
+const routeMap = createRouteMap(machine);
+const disconnect = connectRouter({ actor, routeMap });
+
+onDestroy(disconnect);
+```
+
+## Notes
+
+- `connectRouter()` returns a cleanup function. Call it during teardown to stop syncing actor updates.
+- Actor routes may be either state IDs or resolved paths; the adapter normalizes both.
+- Incoming SvelteKit paths are converted into `play.route` events with extracted `params` and `query`.
+
+## Route map
+
+`createRouteMap(machine)` reads route metadata from the machine and builds a Play route map for SvelteKit paths.
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+
+## Interfaces
+
+- [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.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)