@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,12 +2,12 @@
 
 # Interface: DefineRegistryOptions\<C\>
 
-Defined in: [packages/play-svelte/src/define-registry.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-svelte/src/define-registry.ts#L93)
+Defined in: [packages/play-svelte/src/define-registry.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/define-registry.ts#L94)
 
-Options for `defineRegistry`.
+The options of `defineRegistry`.
 
-Mirrors the upstream shape but replaces the untyped
-`Record<string, DefineRegistryActionFn>` with a catalog-typed `Actions<C>` map.
+The shape is the same as the shape above it, but the untyped
+`Record<string, DefineRegistryActionFn>` becomes the catalog-typed `Actions<C>` map.
 
 ## Type Parameters
 
@@ -17,8 +17,8 @@ Mirrors the upstream shape but replaces the untyped
 
 ## 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/v2.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/v2.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/v2.0.0/packages/play-svelte/src/define-registry.ts#L142) |
+| Property                                             | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Defined in                                                                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-actions"></a> `actions?`             | [`Actions`](../type-aliases/Actions.md)\<`C`\>                | The catalog-typed map of the action handlers. Each handler receives `params` with the exact schema of the catalog action, or `undefined` when the caller gives no params. It also receives the `setState` argument and the `state` argument of the package above. Test for `undefined` before you read a param: **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:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/define-registry.ts#L118) |
+| <a id="property-components"></a> `components?`       | `Components`\<`C`\>                                           | The Svelte component implementations, with the catalog component name as the key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [packages/play-svelte/src/define-registry.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/define-registry.ts#L98)   |
+| <a id="property-onrendererror"></a> `onRenderError?` | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md) | The callback that the renderer calls when a catalog component throws during a render. The inner `<svelte:boundary>` of `@xmachines/json-render-svelte` catches the error, and that boundary wraps each element. With this callback, the default `console.error(...)` fallback does not run: the renderer removes the component from the DOM, and your callback receives the error and the name of the element type. You can then report the error, or you can recover from it. **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 value that the component threw. It is not always an `Error` instance. **Param** **elementType** The name of the catalog component that failed, for example `"Dashboard"`. | [packages/play-svelte/src/define-registry.ts:143](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/define-registry.ts#L143) |

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

@@ -2,14 +2,16 @@
 
 # Interface: PlayUIProviderProps
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-svelte/src/actor-context.svelte.ts#L78)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L82)
 
-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.
+The framework-agnostic base props. Every `ActorProvider` implementation shares
+them: React, Vue, Solid, and Svelte. `TRegistry` holds the
+`DefineRegistryResult` type of the framework. `RenderErrorHandler` comes from
+`@xmachines/json-render-core`, and a second generic parameter is therefore not
+necessary.
 
-Framework packages extend this with their `fallback`, `onError`, and `children` fields.
+Each framework package extends this interface with its `fallback` field, its
+`onError` field, and its `children` field.
 
 ## Example
 
@@ -29,15 +31,15 @@ interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult
 
 ## 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:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L156)             |
-| <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/v2.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/v2.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/v2.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/v2.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/v2.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:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L169)             |
-| <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:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L158)             |
-| <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:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L164)             |
-| <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/v2.0.0/packages/play-svelte/src/actor-context.svelte.ts#L79) |
+| 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) | The actor instance with the currentView signal. It requires the Viewable capability.                                                                                                                                                                                              | [`ActorProviderProps`](ActorProviderProps.md).[`actor`](ActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:163](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L163)             |
+| <a id="property-children"></a> `children`                        | `Snippet`                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                                                                                                 | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)             | [packages/play-svelte/src/actor-context.svelte.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L75) |
+| <a id="property-fallback"></a> `fallback?`                       | `Snippet`\<\[\]\>                                                                                                                                                                                                                                                | -                                                                                                                                                                                                                                                                                 | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)             | [packages/play-svelte/src/actor-context.svelte.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L73) |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `unknown`\>                                                                                                                                                                                                                                  | -                                                                                                                                                                                                                                                                                 | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L88) |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | -                                                                                                                                                                                                                                                                                 | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L87) |
+| <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:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L74) |
+| <a id="property-onrendererror"></a> `onRenderError?`             | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                                                                                    | The provider calls it when one catalog component throws during a render. This handler replaces every onRenderError of defineRegistry.                                                                                                                                             | [`ActorProviderProps`](ActorProviderProps.md).[`onRenderError`](ActorProviderProps.md#property-onrendererror)   | [packages/play-actor/src/abstract-actor.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L177)             |
+| <a id="property-registryresult"></a> `registryResult`            | `DefineRegistryResult`                                                                                                                                                                                                                                           | The complete result of defineRegistry(). It holds the component registry and the factory of the action handlers.                                                                                                                                                                  | [`ActorProviderProps`](ActorProviderProps.md).[`registryResult`](ActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L165)             |
+| <a id="property-store"></a> `store?`                             | `StateStore`                                                                                                                                                                                                                                                     | The optional external StateStore, which is the controlled mode. With this option, the provider ignores spec.state, and this store is the single source of truth. Without it, the provider makes a new @xstate/store atom for each view transition, with the values of spec.state. | [`ActorProviderProps`](ActorProviderProps.md).[`store`](ActorProviderProps.md#property-store)                   | [packages/play-actor/src/abstract-actor.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L172)             |
+| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | -                                                                                                                                                                                                                                                                                 | -                                                                                                               | [packages/play-svelte/src/actor-context.svelte.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L83) |

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

@@ -2,13 +2,14 @@
 
 # Interface: ViewContextValue
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-svelte/src/actor-context.svelte.ts#L47)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L51)
 
-Framework-agnostic base for every framework's `ViewContextValue`.
+The framework-agnostic base of the `ViewContextValue` type in each framework.
 
-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`.
+It holds the three fields that are identical in React, Vue, Solid, and Svelte.
+The `registry` field belongs to one framework, because each framework has its own
+`ComponentRegistry` type. Therefore `TRegistry` gives its type, and this is the
+same generic parameter as in `BaseActorProviderProps`.
 
 ## Extends
 
@@ -16,9 +17,9 @@ type) so it is typed via `TRegistry` — the same generic used in `BaseActorProv
 
 ## 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:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L124) |
-| <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:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L126) |
-| <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:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L122) |
-| <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:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-actor/src/abstract-actor.ts#L128) |
+| Property                                  | Type                                                  | Description                                                                                                            | Inherited from                                                                                                                                                    | Defined in                                                                                                                                               |
+| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-handlers"></a> `handlers` | `Record`\<`string`, `ActionHandler`\>                 | The 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/v2.1.0/packages/play-actor/src/abstract-actor.ts#L127) |
+| <a id="property-registry"></a> `registry` | `TRegistry`                                           | The 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/v2.1.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/v2.1.0/packages/play-actor/src/abstract-actor.ts#L125) |
+| <a id="property-store"></a> `store`       | `StateStore`                                          | The active StateStore. Give it to JSONUIProvider or JsonUIProvider as `store`, and the providers then share the state. | [`BaseViewContextValue`](../../play-actor/interfaces/BaseViewContextValue.md).[`store`](../../play-actor/interfaces/BaseViewContextValue.md#property-store)       | [packages/play-actor/src/abstract-actor.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-actor/src/abstract-actor.ts#L133) |

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

@@ -6,6 +6,6 @@
 type AnyPlayActor = AbstractActor<AnyActorLogic> & Viewable;
 ```
 
-Defined in: [packages/play-svelte/src/actor-context.svelte.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-svelte/src/actor-context.svelte.ts#L22)
+Defined in: [packages/play-svelte/src/actor-context.svelte.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-svelte/src/actor-context.svelte.ts#L25)
 
-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`.
+The actor type that the Svelte `ActorProvider` and `getActorContext` accept. It requires `Viewable` for the view rendering. For the complete routing and view shape, use `PlayActor` from `@xmachines/play-router`.

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

@@ -2,11 +2,9 @@
 
 # @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.
+> Svelte SPA Router adapter for the XMachines Play architecture. It connects hash-based routing to a `Routable` actor, so the state machine owns the navigation.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-svelte-spa-router)
-
-Part of the [XMachines Play monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-svelte-spa-router)
 
 ---
 
@@ -16,7 +14,7 @@ Part of the [XMachines Play monorepo](../../README.md).
 pnpm add @xmachines/play-svelte-spa-router
 ```
 
-**Peer dependencies** — install alongside the adapter:
+**Peer dependencies.** Install them with the adapter:
 
 ```bash
 pnpm add svelte@^5.0.0 svelte-spa-router@^5.0.0 xstate@^5.31.0
@@ -28,7 +26,7 @@ pnpm add svelte@^5.0.0 svelte-spa-router@^5.0.0 xstate@^5.31.0
 
 ### 1. Define a routable XState machine
 
-Declare routes in each state's `meta.route` field:
+Declare the route of each state in its `meta.route` field:
 
 ```typescript
 import { setup } from "xstate";
@@ -52,33 +50,32 @@ const machine = setup({
 
 ### 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:
+Use `createRouteMap` to build a bidirectional route map from the machine. Then call `connectRouter` one time, usually in your root Svelte component or in a dedicated runtime module:
 
 ```typescript
+// runtime.ts
 import { definePlayer } from "@xmachines/play-xstate";
 import { connectRouter, createRouteMap } from "@xmachines/play-svelte-spa-router";
+import { machine } from "./machine.js"; // defined in the previous example
 
 const createPlayer = definePlayer({ machine });
 export const actor = createPlayer();
 actor.start();
 
 const routeMap = createRouteMap(machine);
-const disconnectRouter = connectRouter({ actor, routeMap });
+export const disconnectRouter = connectRouter({ actor, routeMap });
 ```
 
 ### 3. Clean up on destroy
 
-Return the cleanup function from `connectRouter` to `onDestroy` (or your lifecycle equivalent):
+Give the cleanup function of `connectRouter` to `onDestroy`, or to the equivalent lifecycle hook:
 
 ```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 });
+	import { onDestroy } from "svelte";
+	import { disconnectRouter } from "./runtime.js"; // the module from the previous example
 
-  onDestroy(() => disconnect());
+	onDestroy(() => disconnectRouter());
 </script>
 ```
 
@@ -103,20 +100,20 @@ interface ConnectRouterOptions {
 }
 ```
 
-**Behaviour:**
+**Behavior:**
 
-- 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.
+- On `connect`: it reads the current hash URL from `router.loc.location`, sets the actor state with a `play.route` event, and then listens for a `hashchange` event.
+- On a change of the actor `currentRoute`: it calls `push(path)` from svelte-spa-router to update the URL.
+- On `hashchange`: it reads the new location from `router.loc` and sends `play.route` to the actor.
+- On disconnect: it removes the `hashchange` listener and cancels the subscriptions to the 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).
+This function comes from `@xmachines/play-router`. It reads every `meta.route` entry of an XState machine. Then it builds a bidirectional route map with `URLPattern` matching, which includes a parameter segment and an optional segment.
 
 ### `RouteMap`
 
-Re-exported from `@xmachines/play-router`. Bidirectional map between state IDs and URL paths.
+This type comes from `@xmachines/play-router`. It is the bidirectional map between the state IDs and the URL paths.
 
 | Method                      | Description                                    |
 | --------------------------- | ---------------------------------------------- |
@@ -127,9 +124,9 @@ Re-exported from `@xmachines/play-router`. Bidirectional map between state IDs a
 
 | Type                   | Description                                                                                               |
 | ---------------------- | --------------------------------------------------------------------------------------------------------- |
-| `ConnectRouterOptions` | Options accepted by `connectRouter`                                                                       |
+| `ConnectRouterOptions` | The options that `connectRouter` accepts                                                                  |
 | `RoutableActor`        | Minimal actor interface — `AbstractActor` from `@xmachines/play-actor` combined with the `Routable` mixin |
-| `PlayRouteEvent`       | The `play.route` event type sent to the actor                                                             |
+| `PlayRouteEvent`       | The `play.route` event type that the bridge sends to the actor                                            |
 | `RouterBridge`         | Interface that all router bridges must satisfy                                                            |
 | `RouteMapping`         | Route-entry shape within a `RouteMap`                                                                     |
 | `RouteMapOptions`      | Options for `createRouteMap`                                                                              |
@@ -147,7 +144,9 @@ Re-exported from `@xmachines/play-router`. Bidirectional map between state IDs a
 | `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`.
+The bridge reads the initial path from `router.loc.location`, and the initial search string from `router.loc.querystring`. It inherits the restore-or-deeplink detection, the guard-redirect flow, and the `isProcessingNavigation` debounce from `RouterBridgeBase`.
+
+`SvelteSpaRouterBridge` is exported from the package — prefer `connectRouter` for the common case, and instantiate the bridge directly (`new SvelteSpaRouterBridge(actor, routeMap)` followed by `connect()`/`disconnect()`) when you need fine-grained control over the connection lifecycle.
 
 ---
 
@@ -176,6 +175,7 @@ MIT © XMachines Contributors. See [LICENSE](./LICENSE).
 ## Classes
 
 - [RouteMap](classes/RouteMap.md)
+- [SvelteSpaRouterBridge](classes/SvelteSpaRouterBridge.md)
 
 ## Interfaces
 

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

@@ -2,32 +2,33 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L105)
 
-Shared bidirectional route map base class.
+The shared base class of the route map for both directions.
 
-All framework adapters use this class as their route map — they add no logic of their
-own and inherit the full public API from here.
+Every framework adapter uses this class as its route map. An adapter adds no logic
+of its own, and it inherits the complete public API from here.
 
-**Lookup strategy:**
+**The strategy of a lookup:**
 
-- 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)
+- A static path, without a `:param` → a `Map` lookup in O(1)
+- A dynamic path → a scan of the bucket index in O(k), with `URLPattern`, where
+  `k` is the number of the routes with the same first path segment
+- The class keeps each result of a first match in an LRU cache. The default size
+  is 500 entries, and the `cacheSize` constructor option changes it
 
-**Pattern syntax** (`:param` / `:param?` / `*`):
+**The syntax of a pattern** (`:param`, `:param?`, and `*`):
 
-- `:param` — required segment, matches exactly one non-`/` segment
-- `:param?` — optional segment, matches zero or one non-`/` segment
-- `*` — wildcard, matches any number of segments (URLPattern semantics)
+- `:param` — a necessary segment. It matches exactly one segment without a `/`
+- `:param?` — an optional segment. It matches zero segments or one segment without a `/`
+- `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
-**StateId forms:** stateIds may be registered and looked up in either
-`"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
-`getStateIdByPath` returns the stateId exactly as registered;
-`getPathByStateId` accepts both forms. Registering the same stateId in both
-forms refers to one entry (the later registration wins for reverse lookup).
+**The forms of a stateId:** you can register a stateId, and you can look one up,
+in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
+canonical form itself. `getStateIdByPath` returns the stateId exactly as you
+registered it, and `getPathByStateId` accepts both forms. A registration of the
+same stateId in both forms gives one entry, and the later registration wins for
+the lookup in the other direction.
 
 ## Example
 
@@ -57,21 +58,22 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L127)
+Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L133)
 
-Build a route map from an array of state ID ↔ path mappings.
+Builds a route map from an array of the mappings between a state ID and a path.
 
-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.
+The constructor puts each static path, which holds no `:param`, into a `Map` for a
+lookup in O(1). It compiles each parameterized path to a `URLPattern`, and it
+groups the patterns into the buckets of the first segment. The selection of the
+candidates is therefore efficient.
 
 #### 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`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                                                                                                                                                                                                                                                                                                                                                     |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | The optional configuration. `options.cacheSize`: the maximum number of the resolved parameterized path lookups in the cache. The default is `500`. Raise it for an application with many different values in a parameterized URL, for example a page of a user profile with thousands of different IDs. After an eviction, the path goes to the bucket pattern scan in O(k) again, which is correct but slower. The smallest effective value is `1`, because QuickLRU requires it. |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 #### Returns
 
@@ -85,31 +87,31 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [play-router/src/base-route-map.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L225)
 
-Look up the path pattern registered for a state ID.
+Returns the path pattern of a state ID.
 
-Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
-which form was used at registration — lookups are canonicalized internally,
-so consumers never need to try both forms.
+The method accepts the stateId in the form `"#stateId"` and in the form
+`"stateId"`, and the form of the registration has no effect. The method makes the
+canonical form itself. Therefore a consumer tries never both forms.
 
 #### Parameters
 
-| Parameter | Type     | Description                                               |
-| --------- | -------- | --------------------------------------------------------- |
-| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+| Parameter | Type     | Description                                                                 |
+| --------- | -------- | --------------------------------------------------------------------------- |
+| `stateId` | `string` | The state ID of the state machine, for example `"profile"` or `"#settings"` |
 
 #### Returns
 
 `string` \| `null`
 
-The registered path pattern, or `null` if the state ID is unknown
+The registered path pattern, or `null` when the state ID is unknown
 
 #### Example
 
 ```typescript
 map.getPathByStateId("profile"); // "/profile/:userId"
-map.getPathByStateId("#profile"); // "/profile/:userId" (same entry)
+map.getPathByStateId("#profile"); // "/profile/:userId" — the same entry
 map.getPathByStateId("missing"); // null
 ```
 
@@ -121,25 +123,25 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [play-router/src/base-route-map.ts:185](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L185)
 
-Resolve a URL path to its mapped state ID.
+Resolves a URL path to its 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.
+The method removes the query string and the hash fragment before the match. It
+tries an exact lookup in O(1) first, then it uses the pattern match on the bucket
+index. It keeps each result of a first pattern match in the cache.
 
 #### Parameters
 
-| Parameter | Type     | Description                                                                    |
-| --------- | -------- | ------------------------------------------------------------------------------ |
-| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+| Parameter | Type     | Description                                                                            |
+| --------- | -------- | -------------------------------------------------------------------------------------- |
+| `path`    | `string` | The URL pathname. It can hold a query and a hash, for example `"/profile/123?ref=nav"` |
 
 #### Returns
 
 `string` \| `null`
 
-The mapped state ID, or `null` if no route matches
+The state ID of the path, or `null` when no route matches
 
 #### Example