@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,9 +2,9 @@
 
 # Interface: PlayUIProviderProps
 
-Defined in: [packages/play-solid/src/PlayUIProvider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/PlayUIProvider.tsx#L36)
+Defined in: [packages/play-solid/src/PlayUIProvider.tsx:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/PlayUIProvider.tsx#L37)
 
-Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's forwarded props.
+The props of PlayUIProvider — every ActorProvider prop, and also the props that it forwards to JSONUIProvider.
 
 ## Extends
 
@@ -12,15 +12,15 @@ Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's forwa
 
 ## 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/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L159) |
-| <a id="property-children"></a> `children`                        | `any`                                                                                                                                                                                                                                                            | Children — required; must include <PlayRenderer /> (or use PlayUIProvider shorthand)                                                                                                                                        | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-solid/src/ActorProvider.tsx:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/ActorProvider.tsx#L97)   |
-| <a id="property-fallback"></a> `fallback?`                       | `any`                                                                                                                                                                                                                                                            | Optional fallback element shown when currentView is null or ErrorBoundary catches                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-solid/src/ActorProvider.tsx:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/ActorProvider.tsx#L91)   |
-| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                                                                                                                                                                         | Named functions for `$computed` expressions in props                                                                                                                                                                        | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`functions`](JSONUIProviderProps.md#property-functions)                     | -                                                                                                                                                                |
-| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | Navigation function                                                                                                                                                                                                         | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`navigate`](JSONUIProviderProps.md#property-navigate)                       | -                                                                                                                                                                |
-| <a id="property-onerror"></a> `onError?`                         | (`error`) => `void`                                                                                                                                                                                                                                              | Optional callback invoked when SolidJS ErrorBoundary catches an error                                                                                                                                                       | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-solid/src/ActorProvider.tsx:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/ActorProvider.tsx#L94)   |
-| <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/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L172) |
-| <a id="property-registryresult"></a> `registryResult`            | [`DefineRegistryResult`](DefineRegistryResult.md)                                                                                                                                                                                                                | 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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L167) |
-| <a id="property-validationfunctions"></a> `validationFunctions?` | `Record`\<`string`, (`value`, `args?`) => `boolean`\>                                                                                                                                                                                                            | Custom validation functions                                                                                                                                                                                                 | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`validationFunctions`](JSONUIProviderProps.md#property-validationfunctions) | -                                                                                                                                                                |
+| 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`                        | `any`                                                                                                                                                                                                                                                            | The children. They are necessary, and they must hold a <PlayRenderer />. You can also use the PlayUIProvider short form                                                                                                                                                           | [`ActorProviderProps`](ActorProviderProps.md).[`children`](ActorProviderProps.md#property-children)                          | [packages/play-solid/src/ActorProvider.tsx:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L101) |
+| <a id="property-fallback"></a> `fallback?`                       | `any`                                                                                                                                                                                                                                                            | The optional fallback element. The provider shows it when currentView is null, and when the ErrorBoundary catches an error                                                                                                                                                        | [`ActorProviderProps`](ActorProviderProps.md).[`fallback`](ActorProviderProps.md#property-fallback)                          | [packages/play-solid/src/ActorProvider.tsx:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L93)   |
+| <a id="property-functions"></a> `functions?`                     | `Record`\<`string`, `ComputedFunction`\>                                                                                                                                                                                                                         | Named functions for `$computed` expressions in props                                                                                                                                                                                                                              | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`functions`](JSONUIProviderProps.md#property-functions)                     | -                                                                                                                                                        |
+| <a id="property-navigate"></a> `navigate?`                       | (`path`) => `void`                                                                                                                                                                                                                                               | Navigation function                                                                                                                                                                                                                                                               | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`navigate`](JSONUIProviderProps.md#property-navigate)                       | -                                                                                                                                                        |
+| <a id="property-onerror"></a> `onError?`                         | (`error`) => `void`                                                                                                                                                                                                                                              | The optional callback. The provider calls it when the SolidJS ErrorBoundary catches an error                                                                                                                                                                                      | [`ActorProviderProps`](ActorProviderProps.md).[`onError`](ActorProviderProps.md#property-onerror)                            | [packages/play-solid/src/ActorProvider.tsx:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L96)   |
+| <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`](DefineRegistryResult.md)                                                                                                                                                                                                                | 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`\>                                                                                                                                                                                                            | Custom validation functions                                                                                                                                                                                                                                                       | [`JSONUIProviderProps`](JSONUIProviderProps.md).[`validationFunctions`](JSONUIProviderProps.md#property-validationfunctions) | -                                                                                                                                                        |

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

@@ -2,10 +2,10 @@
 
 # Interface: ViewContextValue
 
-Defined in: [packages/play-solid/src/ActorProvider.tsx:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/ActorProvider.tsx#L56)
+Defined in: [packages/play-solid/src/ActorProvider.tsx:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L56)
 
-Value provided by ActorProvider's ViewContext.
-Access via usePlayView() inside the ActorProvider tree.
+The value that the ViewContext of ActorProvider provides.
+usePlayView() gives it inside the ActorProvider tree.
 
 ## Extends
 
@@ -13,9 +13,9 @@ Access via usePlayView() inside the ActorProvider tree.
 
 ## 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/v2.0.0-alpha.1/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/v2.0.0-alpha.1/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.0.0-alpha.1/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/v2.0.0-alpha.1/packages/play-actor/src/abstract-actor.ts#L131) |
+| 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-solid/type-aliases/AnyPlayActor.md

@@ -6,6 +6,6 @@
 type AnyPlayActor = AbstractActor<AnyActorLogic>;
 ```
 
-Defined in: [packages/play-solid/src/useActor.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/useActor.ts#L28)
+Defined in: [packages/play-solid/src/useActor.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/useActor.ts#L30)
 
-Bare actor type accepted by Solid context providers. For the full routing + view shape, use `PlayActor` from `@xmachines/play-router`.
+The bare actor type that the Solid context providers accept. For the complete routing and view shape, use `PlayActor` from `@xmachines/play-router`.

package/api/@xmachines/play-solid/variables/ActorContext.md

@@ -6,8 +6,9 @@
 const ActorContext: Context<AnyPlayActor | null>;
 ```
 
-Defined in: [packages/play-solid/src/useActor.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/useActor.ts#L35)
+Defined in: [packages/play-solid/src/useActor.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/useActor.ts#L38)
 
-SolidJS context for the actor — exported so consumers can use ActorContext.Provider
-directly as an escape hatch (per D-11). The smart ActorProvider component takes
-the name "ActorProvider" and is the recommended entry point.
+The SolidJS context of the actor. This package exports it, so that a consumer
+can use ActorContext.Provider directly for a custom composition (see D-11). The
+ActorProvider component has the name "ActorProvider", and it is the recommended
+entry point.

package/api/@xmachines/play-solid/variables/ActorProvider.md

@@ -6,15 +6,16 @@
 const ActorProvider: Component<ActorProviderProps>;
 ```
 
-Defined in: [packages/play-solid/src/ActorProvider.tsx:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/ActorProvider.tsx#L159)
+Defined in: [packages/play-solid/src/ActorProvider.tsx:165](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L165)
 
-Smart ActorProvider component — owns actor bridging, signal subscription,
-StateStore lifecycle, handler resolution, and error boundary.
+The ActorProvider component. It owns the actor bridge, the signal subscription, the
+StateStore lifecycle, the resolution of the handlers, and the error boundary.
 
-Per D-11: Replaces the old raw alias `ActorProvider = ActorContext.Provider`.
-Consumers who previously used `<ActorProvider value={actor}>` should now use
-`<ActorContext.Provider value={actor}>` for raw provider access, or migrate to
-this smart component / PlayUIProvider.
+D-11: this component replaces the old raw alias
+`ActorProvider = ActorContext.Provider`. A consumer with an
+`<ActorProvider value={actor}>` element takes
+`<ActorContext.Provider value={actor}>` now, for the raw access to the provider.
+That consumer can also move to this component, or to PlayUIProvider.
 
 ## Example
 

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

@@ -6,9 +6,11 @@
 const PlayRenderer: Component;
 ```
 
-Defined in: [packages/play-solid/src/PlayRenderer.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/PlayRenderer.tsx#L27)
+Defined in: [packages/play-solid/src/PlayRenderer.tsx:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/PlayRenderer.tsx#L30)
 
-Zero-prop leaf renderer. Must be placed inside an ActorProvider or PlayUIProvider tree.
+The leaf renderer without props. Put it inside an ActorProvider tree or a
+PlayUIProvider tree.
 
-Reads ViewContextValue (spec, handlers, registry) from the enclosing provider
-via usePlayView() and renders the spec via @xmachines/json-render-solid's Renderer.
+It reads the ViewContextValue (the spec, the handlers, and the registry) of the
+provider around it, with usePlayView(). It then renders the spec with the Renderer
+of @xmachines/json-render-solid.

package/api/@xmachines/play-solid/variables/PlayUIProvider.md

@@ -6,16 +6,16 @@
 const PlayUIProvider: Component<PlayUIProviderProps>;
 ```
 
-Defined in: [packages/play-solid/src/PlayUIProvider.tsx:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-solid/src/PlayUIProvider.tsx#L82)
+Defined in: [packages/play-solid/src/PlayUIProvider.tsx:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/PlayUIProvider.tsx#L84)
 
-Batteries-included composite provider: ActorProvider + JSONUIProvider.
+The composite provider: ActorProvider and JSONUIProvider.
 
-Provides the full JSON render context stack:
+It gives you the complete stack of the JSON render context:
 
-- ActorContext (actor instance via ActorProvider)
-- ViewContext (spec, handlers, registry via ActorProvider)
-- StateProvider + ActionProvider + VisibilityProvider + ValidationProvider (via JSONUIProvider)
-- ConfirmDialogManager (via JSONUIProvider)
+- ActorContext, which holds the actor instance, through ActorProvider
+- ViewContext, which holds the spec, the handlers, and the registry, through ActorProvider
+- StateProvider, ActionProvider, VisibilityProvider, and ValidationProvider, through JSONUIProvider
+- ConfirmDialogManager, through JSONUIProvider
 
 ## Example
 

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

@@ -1,12 +1,10 @@
 [API](../../README.md) / @xmachines/play-solid-router
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-solid-router
 
-SolidJS Router adapter for the XMachines Universal Player Architecture. Provides bidirectional synchronisation between a `PlayerActor`'s state machine routes and the browser URL via `@solidjs/router`.
+SolidJS Router adapter for the XMachines Universal Player Architecture. It keeps the state machine routes of a `PlayerActor` and the browser URL in step, in both directions, through `@solidjs/router`.
 
-Part of the [xmachines-js 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-solid-router)
 
 ## Installation
 
@@ -14,7 +12,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-solid-router
 ```
 
-**Peer dependencies** (must be installed separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add solid-js @solidjs/router xstate
@@ -22,7 +20,7 @@ pnpm add solid-js @solidjs/router xstate
 
 - `solid-js` `^1.8.0`
 - `@solidjs/router` `^0.16.1`
-- `xstate` `^6.0.0-alpha.19`
+- `xstate` `^5.31.0`
 
 ## Quick Start
 
@@ -38,6 +36,10 @@ actor.start();
 
 const routeMap = createRouteMap(myMachine);
 
+// Minimal app shell stub — a real app renders PlayUIProvider + PlayRenderer from
+// @xmachines/play-solid here (see the workspace-only @xmachines/play-solid-demo Shell)
+const MyApp = (props: { actor: typeof actor }) => <main />;
+
 const Layout: ParentComponent = () => {
 	const navigate = useNavigate();
 	const location = useLocation();
@@ -64,7 +66,7 @@ export default function App() {
 
 ### `PlayRouterProvider`
 
-A SolidJS component that wires a `PlayerActor` to Solid Router. It creates and connects a `SolidRouterBridge` on mount and disconnects it via `onCleanup` on unmount.
+This SolidJS component connects a `PlayerActor` to Solid Router. It creates and connects a `SolidRouterBridge` on mount. It disconnects the bridge with `onCleanup` on unmount.
 
 ```tsx
 interface PlayRouterProviderProps<TActor extends PlayActor> {
@@ -85,14 +87,17 @@ interface PlayRouterProviderProps<TActor extends PlayActor> {
 
 ### `SolidRouterBridge`
 
-Low-level class for manual integration. Extends `RouterBridgeBase` from `@xmachines/play-router` and uses Solid's `createEffect` for reactive router→actor sync.
+The low-level class for a manual integration. It extends `RouterBridgeBase` from `@xmachines/play-router`. It uses the Solid `createEffect` to send each router change to the actor.
 
-> **Important:** `connect()` must be called inside a Solid reactive owner (component or `createRoot`). Cleanup is not automatic — call `disconnect()` (or `dispose()`) explicitly, typically in `onCleanup()`.
+> **Important:** call `connect()` inside a Solid reactive owner: a component, or `createRoot`. The bridge does not clean up by itself. Call `disconnect()` or `dispose()` yourself, usually in `onCleanup()`.
 
 ```tsx
-import { useNavigate, useLocation, useParams, onCleanup } from "@solidjs/router";
+import { useNavigate, useLocation, useParams } from "@solidjs/router";
+import { onCleanup } from "solid-js";
 import { SolidRouterBridge, RouteMap } from "@xmachines/play-solid-router";
 
+// actor: your started player (see the Quick Start above)
+
 function App() {
 	const navigate = useNavigate();
 	const location = useLocation();
@@ -113,7 +118,7 @@ function App() {
 
 ### `createRouteMap(machine)`
 
-Factory that builds a `RouteMap` directly from an XState machine definition. Re-exported from `@xmachines/play-router`.
+This factory builds a `RouteMap` directly from an XState machine definition. It comes from `@xmachines/play-router`.
 
 ```ts
 import { createRouteMap } from "@xmachines/play-solid-router";
@@ -123,7 +128,7 @@ const routeMap = createRouteMap(myMachine);
 
 ### `RouteMap` / `RouteMapping`
 
-Bidirectional state ID ↔ URL path mapping. Re-exported from `@xmachines/play-router`.
+The bidirectional map between the state IDs and the URL paths. It comes from `@xmachines/play-router`.
 
 ```ts
 import { RouteMap } from "@xmachines/play-solid-router";
@@ -137,44 +142,44 @@ const routeMap = new RouteMap([
 
 ### Types
 
-| Export                    | Description                                                                                                                                                                                             |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PlayActor`               | `AbstractActor & Routable & Viewable` — canonical actor shape from `@xmachines/play-router`. Required by `PlayRouterProvider`, which renders the current view spec in addition to synchronizing routes. |
-| `RoutableActor`           | Deprecated alias for `PlayActor`. Use `PlayActor` from `@xmachines/play-router` in new code.                                                                                                            |
-| `AbstractActor`           | Re-exported from `@xmachines/play-actor` for convenience when typing renderer callbacks.                                                                                                                |
-| `SolidRouterHooks`        | Shape of the `router` prop: `{ navigate, location, params }`                                                                                                                                            |
-| `PlayRouterProviderProps` | Full props interface for `PlayRouterProvider`                                                                                                                                                           |
-| `PlayRouteEvent`          | Event type sent to the actor on URL change (`play.route`)                                                                                                                                               |
-| `RouterBridge`            | Interface implemented by `SolidRouterBridge`                                                                                                                                                            |
-| `RouteMapOptions`         | Options bag for `RouteMap` construction. Re-exported from `@xmachines/play-router`.                                                                                                                     |
+| Export                    | Description                                                                                                                                                                                                    |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PlayActor`               | `AbstractActor & Routable & Viewable` — the canonical actor shape from `@xmachines/play-router`. `PlayRouterProvider` requires it, because it renders the current view spec and also keeps the routes in step. |
+| `RoutableActor`           | Deprecated alias for `PlayActor`. Use `PlayActor` from `@xmachines/play-router` in new code.                                                                                                                   |
+| `AbstractActor`           | It comes from `@xmachines/play-actor`. Use it for the type of a renderer callback.                                                                                                                             |
+| `SolidRouterHooks`        | Shape of the `router` prop: `{ navigate, location, params }`                                                                                                                                                   |
+| `PlayRouterProviderProps` | Full props interface for `PlayRouterProvider`                                                                                                                                                                  |
+| `PlayRouteEvent`          | The event type that the bridge sends to the actor on a URL change (`play.route`)                                                                                                                               |
+| `RouterBridge`            | The interface that `SolidRouterBridge` implements                                                                                                                                                              |
+| `RouteMapOptions`         | The options object for the `RouteMap` constructor. It comes from `@xmachines/play-router`.                                                                                                                     |
 
 ## Usage Patterns
 
 ### Protected Routes and Guards
 
-Auth guards live entirely inside the state machine, preventing flashes of unauthorized content:
+The auth guards are inside the state machine only. Unauthorized content therefore never appears, not even for a moment:
 
 ```ts
 const machineConfig = {
 	states: {
 		dashboard: {
 			meta: { route: "/dashboard" },
-			always: ({ context }) => {
-				if (context.isAuthenticated) return;
-				return { target: "login" };
+			always: {
+				guard: ({ context }) => !context.isAuthenticated,
+				target: "login",
 			},
 		},
 	},
 };
 ```
 
-When a user navigates to `/dashboard` while unauthenticated:
+A user navigates to `/dashboard`, and the user is not authenticated:
 
 1. Solid Router updates the URL.
-2. Bridge intercepts and sends `play.route` to the actor.
-3. Actor evaluates the guard — denies transition, moves to `login` instead.
-4. Bridge observes new actor route (`/login`) via TC39 Signal.
-5. Bridge calls `navigate("/login")`.
+2. The bridge receives the change and sends `play.route` to the actor.
+3. The actor evaluates the guard. The guard refuses the transition, and the actor moves to `login`.
+4. The bridge reads the new actor route (`/login`) from the TC39 Signal.
+5. The bridge calls `navigate("/login")`.
 
 ### Dynamic Routes with Parameters
 
@@ -188,7 +193,7 @@ const routeMap = new RouteMap([
 // { type: "play.route", to: "#post", params: { userId: "123", postId: "456" }, query: {} }
 ```
 
-Path parameters are extracted from Solid's reactive `useParams()` proxy — no URLPattern polyfill is needed for parameterized routes.
+The bridge reads the path parameters from the reactive `useParams()` proxy of Solid. A parameterized route therefore does not need the URLPattern polyfill.
 
 ## Testing
 
@@ -202,7 +207,7 @@ pnpm --filter @xmachines/play-solid-router test
 pnpm test
 ```
 
-**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce:
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run in real Chromium through Playwright. They cover the asynchronous sequences that jsdom cannot reproduce:
 
 ```bash
 pnpm exec vitest --config vitest.browser.config.ts --project play-solid-router-browser
@@ -215,7 +220,7 @@ Coverage thresholds: **80%** lines, functions, branches, and statements.
 - [@xmachines/play-router](../play-router/README.md) — core router primitives and `RouterBridgeBase`
 - [@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md) — TanStack Solid Router adapter
 - [@xmachines/play-solid](../play-solid/README.md) — SolidJS view renderer
-- [@xmachines/play-xstate](../play-xstate/README.md) — XState v6 player factory
+- [@xmachines/play-xstate](../play-xstate/README.md) — XState v5 player factory
 
 ## Learn More
 

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

@@ -2,32 +2,33 @@
 
 # Class: RouteMap
 
-Defined in: [packages/play-router/src/base-route-map.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L101)
+Defined in: [packages/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: [packages/play-router/src/base-route-map.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L127)
+Defined in: [packages/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: [packages/play-router/src/base-route-map.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L218)
+Defined in: [packages/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: [packages/play-router/src/base-route-map.ts:178](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/base-route-map.ts#L178)
+Defined in: [packages/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