@xmachines/docs 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,44 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / ActorProviderProps
+
+# Interface: ActorProviderProps
+
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L68)
+
+Framework-agnostic base props shared by every `ActorProvider` implementation
+(React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
+`DefineRegistryResult` type; `RenderErrorHandler` is sourced from
+`@xmachines/json-render-core` so no second generic is needed.
+
+Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+
+## Example
+
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
+
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
+
+## Extends
+
+- [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md)\<`DefineRegistryResult`\>
+
+## Extended by
+
+- [`PlayUIProviderProps`](PlayUIProviderProps.md)
+
+## Properties
+
+| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                                           |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L159)             |
+| <a id="property-children"></a> `children`             | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L71) |
+| <a id="property-fallback"></a> `fallback?`            | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L69) |
+| <a id="property-onerror"></a> `onError?`              | (`error`, `reset`) => `void`                                                                                                                                                                                                                                     | -                                                                                                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-svelte/src/actor-context.svelte.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L70) |
+| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L172)             |
+| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L161)             |
+| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L167)             |

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

@@ -0,0 +1,29 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / BaseComponentProps
+
+# Interface: BaseComponentProps\<P\>
+
+Defined in: `@xmachines/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 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / ComponentContext
+
+# Interface: ComponentContext\<C, K\>
+
+Defined in: `@xmachines/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/DefineRegistryOptions.md

@@ -0,0 +1,24 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / DefineRegistryOptions
+
+# Interface: DefineRegistryOptions\<C\>
+
+Defined in: [packages/play-svelte/src/define-registry.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/define-registry.ts#L93)
+
+Options for `defineRegistry`.
+
+Mirrors the upstream shape but replaces the untyped
+`Record<string, DefineRegistryActionFn>` with a catalog-typed `Actions<C>` map.
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |
+
+## Properties
+
+| Property                                             | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-actions"></a> `actions?`             | [`Actions`](../type-aliases/Actions.md)\<`C`\>                | Catalog-typed action handler map. Each handler receives `params` typed to the exact schema defined in the catalog action (or `undefined` if no params were provided), plus the upstream `setState` and `state` arguments. Guard against `undefined` before accessing params: **Example** `actions: { login: async (params) => { if (!params) return; actor.send({ type: "auth.login", username: params.username }); }, logout: async () => actor.send({ type: "auth.logout" }), }`                                                                                                                                                                                                                                                                                                                                                                                                                  | [packages/play-svelte/src/define-registry.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/define-registry.ts#L117) |
+| <a id="property-components"></a> `components?`       | `Components`\<`C`\>                                           | Svelte component implementations — keyed by catalog component name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [packages/play-svelte/src/define-registry.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/define-registry.ts#L97)   |
+| <a id="property-onrendererror"></a> `onRenderError?` | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | Callback invoked when a catalog component throws during render. The error is caught by `@xmachines/json-render-svelte`'s inner `<svelte:boundary>` that wraps each rendered element. When provided, this callback replaces the default `console.error(...)` fallback — the component is silently removed from the DOM and your callback receives the error and the element type name for custom error reporting or recovery logic. **Example** `const { registry, handlers } = defineRegistry(authCatalog, { components: { Login, Dashboard }, actions: { ... }, onRenderError(error, elementType) { console.warn(`Component <${elementType}> crashed:`, error); reportToSentry(error, { componentType: elementType }); }, });` **Param** **error** The thrown value (not necessarily an `Error` instance). **Param** **elementType** The catalog component name that crashed (e.g. `"Dashboard"`). | [packages/play-svelte/src/define-registry.ts:142](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/define-registry.ts#L142) |

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

@@ -0,0 +1,43 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / PlayUIProviderProps
+
+# Interface: PlayUIProviderProps
+
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L78)
+
+Framework-agnostic base props shared by every `ActorProvider` implementation
+(React, Vue, Solid, Svelte). `TRegistry` captures the framework-specific
+`DefineRegistryResult` type; `RenderErrorHandler` is sourced from
+`@xmachines/json-render-core` so no second generic is needed.
+
+Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+
+## Example
+
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-actor";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
+
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
+
+## Extends
+
+- [`ActorProviderProps`](ActorProviderProps.md)
+
+## Properties
+
+| Property                                                         | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                  | Defined in                                                                                                                                                           |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                              | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L159)             |
+| <a id="property-children"></a> `children`                        | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)             | [packages/play-svelte/src/actor-context.svelte.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L71) |
+| <a id="property-fallback"></a> `fallback?`                       | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)             | [packages/play-svelte/src/actor-context.svelte.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L69) |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `unknown`\>                                                                                                                                                                                                                                  | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L84) |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L83) |
+| <a id="property-onerror"></a> `onError?`                         | (`error`, `reset`) => `void`                                                                                                                                                                                                                                     | -                                                                                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)               | [packages/play-svelte/src/actor-context.svelte.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L70) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | Called when an individual catalog component throws during render. Takes precedence over any onRenderError set via defineRegistry.                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L172)             |
+| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L161)             |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | Optional external StateStore (controlled mode). When provided, spec.state is ignored and this store is the single source of truth. When omitted, a fresh @xstate/store atom is created per view transition from spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L167)             |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | -                                                                                                                                                                                                                           | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L79) |

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

@@ -0,0 +1,24 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / ViewContextValue
+
+# Interface: ViewContextValue
+
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L47)
+
+Framework-agnostic base for every framework's `ViewContextValue`.
+
+Holds the three fields that are identical across React, Vue, Solid, and Svelte.
+`registry` is framework-specific (each framework has its own `ComponentRegistry`
+type) so it is typed via `TRegistry` — the same generic used in `BaseActorProviderProps`.
+
+## Extends
+
+- [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md)\<`ComponentRegistry`\>
+
+## Properties
+
+| Property                                  | Type                                                  | Description                                                                                               | Inherited from                                                                                                                                                    | Defined in                                                                                                                                               |
+| ----------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | Action handlers resolved against the live StateStore.                                                     | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`handlers`](../../play-actor/interfaces/BaseViewContextValue.md#property-handlers) | [packages/play-actor/src/abstract-actor.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L127) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                                           | Component registry from registryResult.registry.                                                          | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`registry`](../../play-actor/interfaces/BaseViewContextValue.md#property-registry) | [packages/play-actor/src/abstract-actor.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L129) |
+| <a id="property-spec"></a> `spec`         | [`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) | The current PlaySpec to render.                                                                           | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`spec`](../../play-actor/interfaces/BaseViewContextValue.md#property-spec)         | [packages/play-actor/src/abstract-actor.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L125) |
+| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore — pass to JSONUIProvider/JsonUIProvider as `store` to share state across providers. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-actor/src/abstract-actor.ts#L131) |

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

@@ -0,0 +1,30 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / ActionFn
+
+# Type Alias: ActionFn\<C, K\>
+
+```ts
+type ActionFn<C, K> = (params, setState, state) => Promise<void>;
+```
+
+Defined in: `@xmachines/json-render-svelte`
+
+Action handler function type
+
+## Type Parameters
+
+| Type Parameter                                   |
+| ------------------------------------------------ |
+| `C` _extends_ `Catalog`                          |
+| `K` _extends_ keyof `InferCatalogActions`\<`C`\> |
+
+## Parameters
+
+| Parameter  | Type                                           |
+| ---------- | ---------------------------------------------- |
+| `params`   | `InferActionParams`\<`C`, `K`\> \| `undefined` |
+| `setState` | [`SetState`](SetState.md)                      |
+| `state`    | `StateModel`                                   |
+
+## Returns
+
+`Promise`\<`void`\>

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

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / Actions
+
+# Type Alias: Actions\<C\>
+
+```ts
+type Actions<C> = { [K in keyof InferCatalogActions<C>]: ActionFn<C, K> };
+```
+
+Defined in: `@xmachines/json-render-svelte`
+
+Registry of all action handlers for a catalog
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |

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

@@ -0,0 +1,11 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / AnyPlayActor
+
+# Type Alias: AnyPlayActor
+
+```ts
+type AnyPlayActor = AbstractActor<AnyActorLogic> & Viewable;
+```
+
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-svelte/src/actor-context.svelte.ts#L22)
+
+Actor type accepted by the Svelte `ActorProvider` and `getActorContext` — requires `Viewable` for view rendering. For the full routing + view shape, use `PlayActor` from `@xmachines/play-router`.

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

@@ -0,0 +1,18 @@
+[API](../../../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: `@xmachines/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/JSONUIProviderProps.md

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

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

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

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

@@ -0,0 +1,23 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / RenderErrorHandler
+
+# Type Alias: RenderErrorHandler
+
+```ts
+type RenderErrorHandler = (error, elementType) => void;
+```
+
+Defined in: `@xmachines/json-render-core`
+
+Callback invoked when an individual catalog component throws during render.
+Implemented by each framework renderer's error boundary / error capture mechanism.
+
+## Parameters
+
+| Parameter     | Type      |
+| ------------- | --------- |
+| `error`       | `unknown` |
+| `elementType` | `string`  |
+
+## Returns
+
+`void`

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

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-svelte](../README.md) / SetState
+
+# Type Alias: SetState
+
+```ts
+type SetState = (updater) => void;
+```
+
+Defined in: `@xmachines/json-render-svelte`
+
+State setter function for updating application state
+
+## Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `updater` | (`prev`) => `Record`\<`string`, `unknown`\> |
+
+## Returns
+
+`void`

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

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

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

@@ -0,0 +1,199 @@
+[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@^5.31.0
+```
+
+---
+
+## Usage
+
+### 1. Define a routable XState machine
+
+Declare routes in each state's `meta.route` field:
+
+```typescript
+import { setup } from "xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import type { PlayRouteEvent } from "@xmachines/play-svelte-spa-router";
+
+const machine = setup({
+	types: { events: {} as PlayRouteEvent },
+}).createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { meta: { route: "/home" } },
+			dashboard: { meta: { route: "/dashboard" } },
+			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)