@xmachines/docs 1.0.0-beta.33 → 1.0.0-beta.34

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

@@ -41,7 +41,12 @@ without muting console output.
 - `useBoundProp` — re-exported from `@json-render/solid`
 - `ComponentFn` (type) — re-exported from `@json-render/solid`
 - `ComponentContext` (type) — re-exported from `@json-render/solid`
-- `PlayRendererProps` (type)
+- `ActorProvider` — escape hatch primitive (owns actor bridging, signal bridge, store lifecycle)
+- `PlayUIProvider` — batteries-included composite (wraps `ActorProvider` + `JSONUIProvider`)
+- `usePlayView` — hook for accessing the current view spec inside a provider tree
+- `RenderErrorHandler` (type) — inner per-element error callback signature
+- `ActorProviderProps` (type)
+- `ViewContextValue` (type)
 - `PlayActor` (type)
 
 ## Quick Start
@@ -121,12 +126,9 @@ const machine = setup({
 				meta: {
 					route: "/login",
 					view: {
-						component: "Login",
-						spec: {
-							root: "root",
-							elements: {
-								root: { type: "Login", props: { title: "Sign In" }, children: [] },
-							},
+						root: "root",
+						elements: {
+							root: { type: "Login", props: { title: "Sign In" }, children: [] },
 						},
 					},
 				},
@@ -136,12 +138,9 @@ const machine = setup({
 				meta: {
 					route: "/dashboard",
 					view: {
-						component: "Dashboard",
-						spec: {
-							root: "root",
-							elements: {
-								root: { type: "Dashboard", props: { username: "" }, children: [] },
-							},
+						root: "root",
+						elements: {
+							root: { type: "Dashboard", props: { username: "" }, children: [] },
 						},
 					},
 				},
@@ -168,32 +167,37 @@ const actor = createPlayer();
 actor.start();
 
 function App() {
-	return <PlayRenderer actor={actor} registryResult={registryResult} />;
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 
 ## API Reference
 
-### `PlayRenderer`
+### `PlayUIProvider`
 
-Main component. Subscribes to `actor.currentView` and renders the spec.
+Batteries-included composite provider. Wraps `ActorProvider` + `JSONUIProvider`. Pass `actor` and `registryResult` here, then place `<PlayRenderer />` inside as a zero-prop child.
 
 ```tsx
-<PlayRenderer
+<PlayUIProvider
 	actor={actor}
 	registryResult={registryResult}
 	store={myStore}
 	fallback={<p>Loading…</p>}
-/>
+	onError={(err) => Sentry.captureException(err)}
+	onRenderError={(error, elementType) => console.warn(`<${elementType}> crashed:`, error)}
+>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
 **`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
 **`registryResult`** — The full `DefineRegistryResult` returned by `defineRegistry(catalog, { components, actions })` from `@xmachines/play-solid`.
 
-`defineRegistry` also accepts `onRenderError(error, elementType)`, which receives errors
-caught by `@json-render/solid`'s inner element boundary before the default logger is used.
-
 **`store`** (optional) — Controls per-view UI state (`$state` bindings, form values):
 
 - **Omitted (uncontrolled, default):** A fresh `@xstate/store` atom is created per view transition, seeded from `view.spec.state`.
@@ -206,31 +210,99 @@ import type { StateStore } from "@json-render/core";
 
 const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
 
-<PlayRenderer actor={actor} registryResult={registryResult} store={store} />;
+<PlayUIProvider actor={actor} registryResult={registryResult} store={store}>
+	<PlayRenderer />
+</PlayUIProvider>;
+```
+
+**`fallback`** — Shown when `actor.currentView.get()` is `null`.
+
+**`onError`** — Called when the outer `ErrorBoundary` catches an error. Receives `(error: unknown)`. Use for observability tools.
+
+**`onRenderError`** — Called when an individual catalog component throws during render. Caught by `@json-render/solid`'s inner per-element `ErrorBoundary` — the failed component is silently removed while the rest of the spec continues rendering. `onError` / `fallback` are **not** triggered. When both `onRenderError` on `PlayUIProvider` and on `defineRegistry` are set, the prop wins.
+
+---
+
+### `ActorProvider`
+
+Escape hatch primitive. Owns actor bridging, signal bridge, and store lifecycle. Use this when you need direct control over the provider layer.
+
+```tsx
+import { ActorProvider } from "@xmachines/play-solid";
+
+<ActorProvider
+	actor={actor}
+	registryResult={registryResult}
+	onRenderError={(err, type) => reportError(err, type)}
+>
+	{/* your own JSONUIProvider + PlayRenderer tree */}
+</ActorProvider>;
+```
+
+---
+
+### `PlayRenderer`
+
+Zero-prop leaf component. Must be rendered inside a `PlayUIProvider` (or `ActorProvider`) tree. Subscribes to `actor.currentView` via context and renders the current spec.
+
+```tsx
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+`PlayRenderer` accepts no props — all configuration (`actor`, `registryResult`, `store`, `fallback`, `onError`, `onRenderError`) is provided by the enclosing `PlayUIProvider` or `ActorProvider`.
+
+## Error handling
+
+The provider tree has two layers of error boundaries:
+
+### Outer boundary — `onError` and `fallback`
+
+Wraps the entire renderer via a SolidJS `ErrorBoundary`. Triggered when the spec or store setup throws, or when the inner boundary is not present.
+
+```tsx
+<PlayUIProvider
+	actor={actor}
+	registryResult={registryResult}
+	fallback={<p>Something went wrong.</p>}
+	onError={(err) => Sentry.captureException(err)}
+>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
-**Inner render errors** — You can intercept catalog component render failures without
-overriding the outer Solid error boundary:
+### Inner boundary — `onRenderError`
+
+Each catalog element is individually wrapped in a SolidJS `ErrorBoundary` by `@json-render/solid`. When a component throws, it is silently removed while the rest of the spec continues rendering. The outer boundary is **not** triggered.
+
+Pass `onRenderError` to `PlayUIProvider` (or `ActorProvider`) — overrides any registry-level handler — or bake it into `defineRegistry`:
 
 ```tsx
+// via PlayUIProvider prop
+<PlayUIProvider
+	actor={actor}
+	registryResult={registryResult}
+	onRenderError={(error, elementType) => {
+		console.warn(`<${elementType}> crashed:`, error);
+	}}
+>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+```ts
+// via defineRegistry — bakes the handler into the registry
 const registryResult = defineRegistry(catalog, {
 	components: { Login, Dashboard },
-	actions: {
-		login: async (params) => {
-			if (!params) return;
-			actor.send({ type: "auth.login", username: params.username });
-		},
-		logout: async (params) => {
-			actor.send({ type: "auth.logout" });
-		},
-	},
+	actions: { login: async (params) => { ... }, logout: async () => { ... } },
 	onRenderError(error, elementType) {
 		reportExpectedRenderError(error, elementType);
 	},
 });
 ```
 
-**`fallback`** — Shown when `actor.currentView.get()` is `null`.
+`onRenderError` is typed as `RenderErrorHandler` and exported from `@xmachines/play-solid`.
 
 ---
 
@@ -248,7 +320,7 @@ function LogoutButton() {
 }
 ```
 
-Throws `"useActor() must be called inside <PlayRenderer>"` if called outside the tree.
+Throws `NonNullableError: "useActor() must be called inside <ActorProvider> (or <PlayUIProvider>)"` if called outside the tree.
 
 ---
 
@@ -275,31 +347,75 @@ Priority: **route param fills `undefined` slots; explicit non-`undefined` spec p
 
 @xmachines/play-solid - SolidJS renderer for XMachines Play architecture
 
-Provides a thin SolidJS rendering layer that passively observes actor signals
-and renders UI components via @json-render/solid. SolidJS reactivity is only
-used to trigger re-renders — signals are the source of truth.
+Provides a SolidJS rendering layer that passively observes actor signals and
+renders UI components via @json-render/solid. SolidJS reactivity is only used
+to trigger re-renders — signals are the source of truth.
 
-Re-exports `defineRegistry`, `useBoundProp`, `ComponentFn`, and
-`ComponentContext` from `@json-render/solid` so consumers import everything
-from `@xmachines/play-solid` rather than `@json-render/solid` directly.
+Primary entry point:
+
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+```
+
+For escape-hatch provider composition:
+
+```tsx
+import { ActorProvider, ActorContext, usePlayView } from "@xmachines/play-solid";
+```
 
 ## Interfaces
 
+- [ActionProviderProps](interfaces/ActionProviderProps.md)
+- [ActorProviderProps](interfaces/ActorProviderProps.md)
 - [ComponentContext](interfaces/ComponentContext.md)
-- [PlayRendererProps](interfaces/PlayRendererProps.md)
+- [DefineRegistryResult](interfaces/DefineRegistryResult.md)
+- [JSONUIProviderProps](interfaces/JSONUIProviderProps.md)
+- [PlayUIProviderProps](interfaces/PlayUIProviderProps.md)
+- [RendererProps](interfaces/RendererProps.md)
+- [StateProviderProps](interfaces/StateProviderProps.md)
+- [ValidationProviderProps](interfaces/ValidationProviderProps.md)
+- [ViewContextValue](interfaces/ViewContextValue.md)
 
 ## Type Aliases
 
 - [ComponentFn](type-aliases/ComponentFn.md)
+- [ComponentRegistry](type-aliases/ComponentRegistry.md)
 - [PlayActor](type-aliases/PlayActor.md)
 - [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
+- [SetState](type-aliases/SetState.md)
+- [VisibilityProviderProps](type-aliases/VisibilityProviderProps.md)
 
 ## Variables
 
+- [ActorContext](variables/ActorContext.md)
+- [ActorProvider](variables/ActorProvider.md)
 - [PlayRenderer](variables/PlayRenderer.md)
+- [PlayUIProvider](variables/PlayUIProvider.md)
 
 ## Functions
 
+- [ActionProvider](functions/ActionProvider.md)
 - [defineRegistry](functions/defineRegistry.md)
+- [JSONUIProvider](functions/JSONUIProvider.md)
+- [Renderer](functions/Renderer.md)
+- [StateProvider](functions/StateProvider.md)
+- [useAction](functions/useAction.md)
+- [useActions](functions/useActions.md)
 - [useActor](functions/useActor.md)
 - [useBoundProp](functions/useBoundProp.md)
+- [useFieldValidation](functions/useFieldValidation.md)
+- [useIsVisible](functions/useIsVisible.md)
+- [useOptionalValidation](functions/useOptionalValidation.md)
+- [usePlayView](functions/usePlayView.md)
+- [useStateBinding](functions/useStateBinding.md)
+- [useStateStore](functions/useStateStore.md)
+- [useStateValue](functions/useStateValue.md)
+- [useVisibility](functions/useVisibility.md)
+- [ValidationProvider](functions/ValidationProvider.md)
+- [VisibilityProvider](functions/VisibilityProvider.md)
+
+## References
+
+### RenderErrorHandler
+
+Re-exports [RenderErrorHandler](type-aliases/RenderErrorHandler.md)

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

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / ActionProvider
+
+# Function: ActionProvider()
+
+```ts
+function ActionProvider(props): any;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter | Type                                                                           |
+| --------- | ------------------------------------------------------------------------------ |
+| `props`   | `ParentProps`\<[`ActionProviderProps`](../interfaces/ActionProviderProps.md)\> |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / JSONUIProvider
+
+# Function: JSONUIProvider()
+
+```ts
+function JSONUIProvider(props): any;
+```
+
+Defined in: `@json-render/solid`
+
+Combined provider for all JSONUI contexts
+
+## Parameters
+
+| Parameter | Type                                                          |
+| --------- | ------------------------------------------------------------- |
+| `props`   | [`JSONUIProviderProps`](../interfaces/JSONUIProviderProps.md) |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / Renderer
+
+# Function: Renderer()
+
+```ts
+function Renderer(props): any;
+```
+
+Defined in: `@json-render/solid`
+
+Main renderer component
+
+## Parameters
+
+| Parameter | Type                                              |
+| --------- | ------------------------------------------------- |
+| `props`   | [`RendererProps`](../interfaces/RendererProps.md) |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / StateProvider
+
+# Function: StateProvider()
+
+```ts
+function StateProvider(props): any;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter | Type                                                                         |
+| --------- | ---------------------------------------------------------------------------- |
+| `props`   | `ParentProps`\<[`StateProviderProps`](../interfaces/StateProviderProps.md)\> |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / ValidationProvider
+
+# Function: ValidationProvider()
+
+```ts
+function ValidationProvider(props): any;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter | Type                                                                                   |
+| --------- | -------------------------------------------------------------------------------------- |
+| `props`   | `ParentProps`\<[`ValidationProviderProps`](../interfaces/ValidationProviderProps.md)\> |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,20 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / VisibilityProvider
+
+# Function: VisibilityProvider()
+
+```ts
+function VisibilityProvider(props): any;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter         | Type                      |
+| ----------------- | ------------------------- |
+| `props`           | \{ `children?`: `any`; \} |
+| `props.children?` | `any`                     |
+
+## Returns
+
+`any`

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

@@ -27,7 +27,7 @@ When the catalog declares actions, the `actions` field is required.
 
 ## Returns
 
-`DefineRegistryResult`
+[`DefineRegistryResult`](../interfaces/DefineRegistryResult.md)
 
 ## Example
 

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

@@ -0,0 +1,24 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useAction
+
+# Function: useAction()
+
+```ts
+function useAction(binding): object;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter | Type            |
+| --------- | --------------- |
+| `binding` | `ActionBinding` |
+
+## Returns
+
+`object`
+
+| Name        | Type                      | Defined in |
+| ----------- | ------------------------- | ---------- |
+| `execute()` | () => `Promise`\<`void`\> | -          |
+| `isLoading` | `boolean`                 | -          |

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

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useActions
+
+# Function: useActions()
+
+```ts
+function useActions(): ActionContextValue;
+```
+
+Defined in: `@json-render/solid`
+
+## Returns
+
+`ActionContextValue`

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

@@ -6,7 +6,7 @@
 function useActor(): PlayActor;
 ```
 
-Defined in: [packages/play-solid/src/useActor.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/useActor.ts#L49)
+Defined in: [packages/play-solid/src/useActor.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/src/useActor.ts#L36)
 
 ## Returns
 

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

@@ -0,0 +1,29 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useFieldValidation
+
+# Function: useFieldValidation()
+
+```ts
+function useFieldValidation(path, config?): object;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter | Type               |
+| --------- | ------------------ |
+| `path`    | `string`           |
+| `config?` | `ValidationConfig` |
+
+## Returns
+
+`object`
+
+| Name         | Type                                 | Defined in |
+| ------------ | ------------------------------------ | ---------- |
+| `clear()`    | () => `void`                         | -          |
+| `errors`     | `Accessor`\<`string`[]\>             | -          |
+| `isValid`    | `Accessor`\<`boolean`\>              | -          |
+| `state`      | `Accessor`\<`FieldValidationState`\> | -          |
+| `touch()`    | () => `void`                         | -          |
+| `validate()` | () => `ValidationResult`             | -          |

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

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useIsVisible
+
+# Function: useIsVisible()
+
+```ts
+function useIsVisible(condition): boolean;
+```
+
+Defined in: `@json-render/solid`
+
+## Parameters
+
+| Parameter   | Type                                 |
+| ----------- | ------------------------------------ |
+| `condition` | `VisibilityCondition` \| `undefined` |
+
+## Returns
+
+`boolean`

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

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useOptionalValidation
+
+# Function: useOptionalValidation()
+
+```ts
+function useOptionalValidation(): ValidationContextValue | null;
+```
+
+Defined in: `@json-render/solid`
+
+## Returns
+
+`ValidationContextValue` \| `null`

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

@@ -0,0 +1,30 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / usePlayView
+
+# Function: usePlayView()
+
+```ts
+function usePlayView(): ViewContextValue;
+```
+
+Defined in: [packages/play-solid/src/ActorProvider.tsx:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-solid/src/ActorProvider.tsx#L61)
+
+Hook to access the current view context inside an ActorProvider tree.
+
+## Returns
+
+[`ViewContextValue`](../interfaces/ViewContextValue.md)
+
+## Throws
+
+If called outside an ActorProvider (or PlayUIProvider) tree
+
+## Example
+
+```tsx
+import { usePlayView } from "@xmachines/play-solid";
+
+const MyRenderer: Component = () => {
+	const view = usePlayView();
+	return <Renderer spec={view.spec} registry={view.registry} />;
+};
+```

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

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useStateBinding
+
+# Function: useStateBinding()
+
+```ts
+function useStateBinding<T>(path): [Accessor<T | undefined>, (value) => void];
+```
+
+Defined in: `@json-render/solid`
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+## Returns
+
+\[`Accessor`\<`T` \| `undefined`\>, (`value`) => `void`\]

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

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useStateStore
+
+# Function: useStateStore()
+
+```ts
+function useStateStore(): StateContextValue;
+```
+
+Defined in: `@json-render/solid`
+
+## Returns
+
+`StateContextValue`

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

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useStateValue
+
+# Function: useStateValue()
+
+```ts
+function useStateValue<T>(path): Accessor<T | undefined>;
+```
+
+Defined in: `@json-render/solid`
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+## Returns
+
+`Accessor`\<`T` \| `undefined`\>

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

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / useVisibility
+
+# Function: useVisibility()
+
+```ts
+function useVisibility(): VisibilityContextValue;
+```
+
+Defined in: `@json-render/solid`
+
+## Returns
+
+`VisibilityContextValue`

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

@@ -0,0 +1,12 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / ActionProviderProps
+
+# Interface: ActionProviderProps
+
+Defined in: `@json-render/solid`
+
+## Properties
+
+| Property                                   | Type                                  | Defined in |
+| ------------------------------------------ | ------------------------------------- | ---------- |
+| <a id="property-handlers"></a> `handlers?` | `Record`\<`string`, `ActionHandler`\> | -          |
+| <a id="property-navigate"></a> `navigate?` | (`path`) => `void`                    | -          |