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

package/api/@xmachines/play-svelte/functions/defineRegistry.md

@@ -0,0 +1,54 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / defineRegistry
+
+# Function: defineRegistry()
+
+```ts
+function defineRegistry<C, TComponents>(_catalog, options): DefineRegistryResult;
+```
+
+Defined in: `@json-render/svelte`
+
+Create a registry from a catalog with Svelte components and/or actions.
+
+Components must accept `BaseComponentProps` as their props interface.
+
+## Type Parameters
+
+| Type Parameter                                                                                                                                     |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `C` _extends_ `Catalog`\<`SchemaDefinition`\<`SchemaType`\<`string`, `unknown`\>, `SchemaType`\<`string`, `unknown`\>\>, `unknown`\>               |
+| `TComponents` _extends_ `Record`\<`string`, `Component`\<[`BaseComponentProps`](../interfaces/BaseComponentProps.md)\<`any`\>, \{ \}, `string`\>\> |
+
+## Parameters
+
+| Parameter             | Type                                                                                            | Description                                      |
+| --------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `_catalog`            | `C`                                                                                             | -                                                |
+| `options`             | \{ `actions?`: `Record`\<`string`, `DefineRegistryActionFn`\>; `components?`: `TComponents`; \} | -                                                |
+| `options.actions?`    | `Record`\<`string`, `DefineRegistryActionFn`\>                                                  | Action handlers                                  |
+| `options.components?` | `TComponents`                                                                                   | Svelte components that accept BaseComponentProps |
+
+## Returns
+
+`DefineRegistryResult`
+
+## Example
+
+```ts
+import { defineRegistry } from "@json-render/svelte";
+import Card from "./components/Card.svelte";
+import Button from "./components/Button.svelte";
+import { myCatalog } from "./catalog";
+
+const { registry, handlers } = defineRegistry(myCatalog, {
+	components: {
+		Card,
+		Button,
+	},
+	actions: {
+		submit: async (params, setState) => {
+			// handle action
+		},
+	},
+});
+```

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

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / BaseComponentProps
+
+# Interface: BaseComponentProps\<P\>
+
+Defined in: `@json-render/svelte`
+
+Catalog-agnostic base type for component render function arguments.
+Use this when building reusable component libraries.
+
+## Extended by
+
+- [`ComponentContext`](ComponentContext.md)
+
+## Type Parameters
+
+| Type Parameter | Default type                    |
+| -------------- | ------------------------------- |
+| `P`            | `Record`\<`string`, `unknown`\> |
+
+## Properties
+
+| Property                                   | Type                           | Description                                                                                                                      | Defined in |
+| ------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-bindings"></a> `bindings?` | `Record`\<`string`, `string`\> | Two-way binding paths resolved from `$bindState` / `$bindItem` expressions. Maps prop name → absolute state path for write-back. | -          |
+| <a id="property-children"></a> `children?` | `Snippet`\<\[\]\>              | -                                                                                                                                | -          |
+| <a id="property-emit"></a> `emit`          | (`event`) => `void`            | Simple event emitter (shorthand). Fires the event and returns void.                                                              | -          |
+| <a id="property-loading"></a> `loading?`   | `boolean`                      | -                                                                                                                                | -          |
+| <a id="property-on"></a> `on`              | (`event`) => `EventHandle`     | Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks.                                       | -          |
+| <a id="property-props"></a> `props`        | `P`                            | -                                                                                                                                | -          |

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

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / ComponentContext
+
+# Interface: ComponentContext\<C, K\>
+
+Defined in: `@json-render/svelte`
+
+Context passed to component render functions
+
+## Extends
+
+- [`BaseComponentProps`](BaseComponentProps.md)\<`InferComponentProps`\<`C`, `K`\>\>
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Properties
+
+| Property                                   | Type                           | Description                                                                                                                      | Inherited from                                                                                      | Defined in |
+| ------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-bindings"></a> `bindings?` | `Record`\<`string`, `string`\> | Two-way binding paths resolved from `$bindState` / `$bindItem` expressions. Maps prop name → absolute state path for write-back. | [`BaseComponentProps`](BaseComponentProps.md).[`bindings`](BaseComponentProps.md#property-bindings) | -          |
+| <a id="property-children"></a> `children?` | `Snippet`\<\[\]\>              | -                                                                                                                                | [`BaseComponentProps`](BaseComponentProps.md).[`children`](BaseComponentProps.md#property-children) | -          |
+| <a id="property-emit"></a> `emit`          | (`event`) => `void`            | Simple event emitter (shorthand). Fires the event and returns void.                                                              | [`BaseComponentProps`](BaseComponentProps.md).[`emit`](BaseComponentProps.md#property-emit)         | -          |
+| <a id="property-loading"></a> `loading?`   | `boolean`                      | -                                                                                                                                | [`BaseComponentProps`](BaseComponentProps.md).[`loading`](BaseComponentProps.md#property-loading)   | -          |
+| <a id="property-on"></a> `on`              | (`event`) => `EventHandle`     | Get an event handle with metadata. Use when you need shouldPreventDefault or bound checks.                                       | [`BaseComponentProps`](BaseComponentProps.md).[`on`](BaseComponentProps.md#property-on)             | -          |
+| <a id="property-props"></a> `props`        | `InferComponentProps`          | -                                                                                                                                | [`BaseComponentProps`](BaseComponentProps.md).[`props`](BaseComponentProps.md#property-props)       | -          |

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.26/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.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

@@ -0,0 +1,18 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / ComponentFn
+
+# Type Alias: ComponentFn\<C, K\>
+
+```ts
+type ComponentFn<C, K> = Component<BaseComponentProps<InferComponentProps<C, K>>>;
+```
+
+Defined in: `@json-render/svelte`
+
+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,9 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte](../README.md) / PlayRenderer
+
+# Type Alias: PlayRenderer
+
+```ts
+type PlayRenderer = SvelteComponent;
+```
+
+Defined in: `svelte`

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

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

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,54 @@
+[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)
+- [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,137 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+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.
+
+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 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, options?): BaseRouteMap;
+```
+
+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.
+
+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
+
+`BaseRouteMap`
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+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.
+
+#### 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
+```
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+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.
+
+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 @@
+[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: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
+
+| 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,38 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+function createRouteMap(machine): RouteMap;
+```
+
+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                                                                      | 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

@@ -0,0 +1,17 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / ConnectRouterOptions
+
+# Interface: ConnectRouterOptions
+
+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
+
+Svelte SPA router adapter for XMachines Play architecture.
+
+## Properties
+
+| 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

@@ -0,0 +1,119 @@
+[Documentation](../../../README.md) / [@xmachines/play-svelte-spa-router](../README.md) / PlayRouteEvent
+
+# Interface: PlayRouteEvent
+
+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
+
+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
+
+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 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" }, // 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: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

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