@xmachines/docs 2.0.0 → 2.1.0

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

@@ -4,11 +4,9 @@
 
 > Solid renderer for XMachines Play architecture
 
-[![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-solid)
+[![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)
 
-SolidJS rendering layer that passively observes actor signals and renders UI components via `@xmachines/json-render-solid`. SolidJS reactivity is used solely to trigger re-renders — TC39 Signals are the source of truth.
-
-Part of the [xmachines-js monorepo](../../README.md).
+The SolidJS rendering layer observes the actor signals and renders the UI components through `@xmachines/json-render-solid`. SolidJS reactivity only triggers the re-render. The TC39 Signals are the source of truth.
 
 ## Installation
 
@@ -16,7 +14,7 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-solid
 ```
 
-**Peer dependencies** — install alongside the package:
+**Peer dependencies.** Install them with the package:
 
 ```bash
 pnpm add solid-js xstate @xstate/store @xmachines/json-render-solid @xmachines/json-render-core @xmachines/json-render-xstate
@@ -29,15 +27,24 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-so
 import { definePlayer } from "@xmachines/play-xstate";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/json-render-solid/schema";
+import { myMachine } from "./machine.js"; // your xstate machine (states carry meta.view specs)
+// authCatalogDef is a plain object describing components/actions — in this repo it
+// comes from the workspace-only @xmachines/play-actor-shared demo package
+import { authCatalogDef } from "@xmachines/play-actor-shared";
 
-// 1. Define a catalog (authCatalogDef is a plain object describing components/actions)
+// 1. Define a catalog
 const catalog = defineCatalog(schema, authCatalogDef);
 
-// 2. Build a component registry
+// 2. Create and start an actor
+const createPlayer = definePlayer({ machine: myMachine });
+const actor = createPlayer();
+actor.start();
+
+// 3. Build a component registry
 const registryResult = defineRegistry(catalog, {
 	components: {
 		Home: () => <div>Welcome home!</div>,
-		Login: (ctx) => <div>Login {ctx.props.error && <span>{ctx.props.error}</span>}</div>,
+		Login: (ctx) => <div>Login {ctx.props.username && <span>{ctx.props.username}</span>}</div>,
 	},
 	actions: {
 		login: async (args) => actor.send({ type: "auth.login", username: args.username }),
@@ -45,11 +52,6 @@ const registryResult = defineRegistry(catalog, {
 	},
 });
 
-// 3. Create and start an actor
-const createPlayer = definePlayer({ machine: myMachine });
-const actor = createPlayer();
-actor.start();
-
 // 4. Render
 function App() {
 	return (
@@ -64,30 +66,32 @@ function App() {
 
 ### `PlayUIProvider` + `PlayRenderer` (recommended)
 
-`PlayUIProvider` is the batteries-included entry point. It wraps `ActorProvider` and `JSONUIProvider` into a single composite provider. `PlayRenderer` is a zero-prop leaf component that reads view context and renders the current spec.
+`PlayUIProvider` is the standard entry point. It wraps `ActorProvider` and `JSONUIProvider` into one composite provider. `PlayRenderer` is a leaf component without props. It reads the view context and renders the current spec.
 
 ```tsx
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
 
+// actor, registryResult from the Quick Start above
 <PlayUIProvider
 	actor={actor}
 	registryResult={registryResult}
 	fallback={<div>Loading…</div>}
 	onError={(err) => console.error(err)}
-	navigate={navigateFn} // optional: passed to JSONUIProvider
-	validationFunctions={valFns} // optional: form validation helpers
+	navigate={navigateFn} // optional: your navigation callback, passed to JSONUIProvider
+	validationFunctions={valFns} // optional: your form validation helpers
 >
 	<PlayRenderer />
 </PlayUIProvider>;
 ```
 
-### `ActorProvider` (escape hatch)
+### `ActorProvider` (low-level)
 
 For library authors who need direct control over provider composition:
 
 ```tsx
 import { ActorProvider, PlayRenderer } from "@xmachines/play-solid";
 
+// actor, registryResult from the Quick Start above
 <ActorProvider actor={actor} registryResult={registryResult}>
 	<PlayRenderer />
 </ActorProvider>;
@@ -124,28 +128,28 @@ const MyRenderer = () => {
 
 ### Components
 
-| Export           | Description                                                                    |
-| ---------------- | ------------------------------------------------------------------------------ |
-| `PlayUIProvider` | Batteries-included composite provider (recommended entry point)                |
-| `PlayRenderer`   | Zero-prop leaf component; renders the current view spec inside a provider tree |
-| `ActorProvider`  | Lower-level smart provider for escape-hatch composition                        |
+| Export           | Description                                                                               |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| `PlayUIProvider` | The composite provider. Use it as the standard entry point                                |
+| `PlayRenderer`   | The leaf component without props. It renders the current view spec inside a provider tree |
+| `ActorProvider`  | The low-level provider for a custom provider composition                                  |
 
 ### Hooks
 
-| Export          | Description                                                                                   |
-| --------------- | --------------------------------------------------------------------------------------------- |
-| `useActor()`    | Returns the raw `AnyPlayActor` instance from context; throws outside a provider tree          |
-| `usePlayView()` | Returns the current `ViewContextValue` (spec, handlers, registry, store); throws outside tree |
+| Export          | Description                                                                                          |
+| --------------- | ---------------------------------------------------------------------------------------------------- |
+| `useActor()`    | Returns the raw `AnyPlayActor` instance from the context. It throws outside a provider tree          |
+| `usePlayView()` | Returns the current `ViewContextValue` (spec, handlers, registry, store). It throws outside the tree |
 
 ### Context
 
-| Export         | Description                                                                            |
-| -------------- | -------------------------------------------------------------------------------------- |
-| `ActorContext` | SolidJS context for the actor; use `ActorContext.Provider` directly as an escape hatch |
+| Export         | Description                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------------------- |
+| `ActorContext` | The SolidJS context of the actor. Use `ActorContext.Provider` directly for a custom composition |
 
 ### Re-exports from `@xmachines/json-render-solid`
 
-This package re-exports the full `@xmachines/json-render-solid` public API so consumers do not need a direct dependency:
+This package re-exports the complete `@xmachines/json-render-solid` public API, so that a consumer does not need a direct dependency:
 
 ```tsx
 import {
@@ -174,12 +178,12 @@ import {
 
 ### Key Types
 
-| Type                  | Description                                                                    |
-| --------------------- | ------------------------------------------------------------------------------ |
-| `PlayUIProviderProps` | Props for `PlayUIProvider`                                                     |
-| `ActorProviderProps`  | Props for `ActorProvider`                                                      |
-| `ViewContextValue`    | Shape of the context value from `usePlayView()`                                |
-| `AnyPlayActor`        | `AbstractActor<AnyActorLogic>` — bare actor type accepted by context providers |
+| Type                  | Description                                                                            |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| `PlayUIProviderProps` | Props for `PlayUIProvider`                                                             |
+| `ActorProviderProps`  | Props for `ActorProvider`                                                              |
+| `ViewContextValue`    | Shape of the context value from `usePlayView()`                                        |
+| `AnyPlayActor`        | `AbstractActor<AnyActorLogic>` — the bare actor type that the context providers accept |
 
 ## Testing
 
@@ -197,17 +201,17 @@ pnpm run test:watch  # watch mode
 pnpm run test:ui     # interactive Vitest UI
 ```
 
-Coverage is collected with v8 (80% threshold for lines, functions, branches, and statements). Browser-specific tests live in `test/browser/` and are excluded from the default jsdom run.
+The v8 provider collects the coverage, with a threshold of 80% for lines, functions, branches, and statements. The browser tests are in `test/browser/`. The default jsdom run excludes them.
 
 ## License
 
 MIT
 
-@xmachines/play-solid - SolidJS renderer for XMachines Play architecture
+@xmachines/play-solid - SolidJS renderer for the XMachines Play architecture
 
-Provides a SolidJS rendering layer that passively observes actor signals and
-renders UI components via @xmachines/json-render-solid. SolidJS reactivity is only used
-to trigger re-renders — signals are the source of truth.
+This package is the SolidJS rendering layer. It observes the actor signals and
+renders the UI components through @xmachines/json-render-solid. SolidJS
+reactivity only triggers the re-render. The signals are the source of truth.
 
 Primary entry point:
 
@@ -215,7 +219,7 @@ Primary entry point:
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
 ```
 
-For escape-hatch provider composition:
+For a custom provider composition:
 
 ```tsx
 import { ActorProvider, ActorContext, usePlayView } from "@xmachines/play-solid";

package/api/@xmachines/play-solid/functions/useActor.md

@@ -6,7 +6,7 @@
 function useActor(): AnyPlayActor;
 ```
 
-Defined in: [packages/play-solid/src/useActor.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid/src/useActor.ts#L37)
+Defined in: [packages/play-solid/src/useActor.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/useActor.ts#L40)
 
 ## Returns
 

package/api/@xmachines/play-solid/functions/usePlayView.md

@@ -6,9 +6,9 @@
 function usePlayView(): ViewContextValue;
 ```
 
-Defined in: [packages/play-solid/src/ActorProvider.tsx:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid/src/ActorProvider.tsx#L75)
+Defined in: [packages/play-solid/src/ActorProvider.tsx:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L75)
 
-Hook to access the current view context inside an ActorProvider tree.
+The hook that gives the current view context inside an ActorProvider tree.
 
 ## Returns
 
@@ -16,7 +16,7 @@ Hook to access the current view context inside an ActorProvider tree.
 
 ## Throws
 
-If called outside an ActorProvider (or PlayUIProvider) tree
+When the caller is outside an ActorProvider tree or a PlayUIProvider tree
 
 ## Example
 

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

@@ -2,12 +2,12 @@
 
 # Interface: ActorProviderProps
 
-Defined in: [packages/play-solid/src/ActorProvider.tsx:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid/src/ActorProvider.tsx#L89)
+Defined in: [packages/play-solid/src/ActorProvider.tsx:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-solid/src/ActorProvider.tsx#L89)
 
-Props for ActorProvider — the escape hatch primitive.
+The props of ActorProvider, the low-level provider.
 
-For batteries-included usage, prefer PlayUIProvider which wraps ActorProvider
-with JSONUIProvider and all required sub-providers.
+For the standard use, prefer PlayUIProvider. That component wraps ActorProvider
+with JSONUIProvider and with every necessary sub-provider.
 
 ## Extends
 
@@ -19,12 +19,12 @@ with JSONUIProvider and all required sub-providers.
 
 ## Properties
 
-| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                               |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts: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`             | `any`                                                                                                                                                                                                                                                            | Children — required; must include <PlayRenderer /> (or use PlayUIProvider shorthand)                                                                                                                                        | -                                                                                                                                                                                   | [packages/play-solid/src/ActorProvider.tsx:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/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                                                                                                                                           | -                                                                                                                                                                                   | [packages/play-solid/src/ActorProvider.tsx:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-solid/src/ActorProvider.tsx#L91)   |
-| <a id="property-onerror"></a> `onError?`              | (`error`) => `void`                                                                                                                                                                                                                                              | Optional callback invoked when SolidJS ErrorBoundary catches an error                                                                                                                                                       | -                                                                                                                                                                                   | [packages/play-solid/src/ActorProvider.tsx:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/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.                                                                                           | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.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`](DefineRegistryResult.md)                                                                                                                                                                                                                | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts: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. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.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) |
+| 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.                                                                                                                                                                                              | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.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                                                                                                                                                           | -                                                                                                                                                                                   | [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                                                                                                                                                        | -                                                                                                                                                                                   | [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-onerror"></a> `onError?`              | (`error`) => `void`                                                                                                                                                                                                                                              | The optional callback. The provider calls it when the SolidJS ErrorBoundary catches an error                                                                                                                                                                                      | -                                                                                                                                                                                   | [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.                                                                                                                                             | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`onRenderError`](../../play-actor/interfaces/BaseActorProviderProps.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.                                                                                                                                                                  | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.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. | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`store`](../../play-actor/interfaces/BaseActorProviderProps.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) |

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/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: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`                        | `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/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/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/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: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`](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: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`\>                                                                                                                                                                                                            | 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/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: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-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/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/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/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/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/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