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

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

@@ -43,14 +43,19 @@ without muting console output.
 - `useBoundProp` — re-exported from `@json-render/react`
 - `ComponentFn` (type) — re-exported from `@json-render/react`
 - `ComponentContext` (type) — re-exported from `@json-render/react`
-- `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
 
 ```tsx
 import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { PlayRenderer } from "@xmachines/play-react";
+import { PlayUIProvider, PlayRenderer } from "@xmachines/play-react";
 import { defineCatalog } from "@json-render/core";
 import { defineRegistry } from "@xmachines/play-react";
 import type { ComponentFn } from "@xmachines/play-react";
@@ -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: [] },
 						},
 					},
 				},
@@ -171,31 +170,36 @@ 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} // required
 	registryResult={registryResult} // required
 	store={myStore} // optional — controlled mode
 	fallback={<p>Loading…</p>} // optional
-/>
+	onError={(err, info) => Sentry.captureException(err, { extra: info })} // optional
+	onRenderError={(error, elementType) => console.warn(`<${elementType}> crashed:`, error)} // optional
+>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
 **`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-**`registryResult`** — Full result from `defineRegistry(catalog, { components, actions })`. Pass the entire return value — contains both the component registry and action handlers. Action handlers are real async functions dispatching to the actor, not string event-type maps.
-
-`defineRegistry` also accepts `onRenderError(error, elementType)`, which receives errors
-caught by `@json-render/react`'s inner element boundary before the default logger is used.
+**`registryResult`** — Full result from `defineRegistry(catalog, { components, actions })`. Contains both the component registry and action handlers.
 
 **`store`** (optional) — Controls per-view UI state (form values, `$state` bindings):
 
@@ -209,31 +213,99 @@ import type { StateStore } from "@json-render/core";
 
 const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "alice" }) });
 
-<PlayRenderer actor={actor} registryResult={registryResult} store={store} />;
+<PlayUIProvider actor={actor} registryResult={registryResult} store={store}>
+	<PlayRenderer />
+</PlayUIProvider>;
 ```
 
-**Inner render errors** — You can intercept catalog component render failures without
-overriding the outer `PlayErrorBoundary`:
+**`fallback`** — Shown when `actor.currentView.get()` is `null` (machine in a no-view state, or during initialisation).
+
+**`onError`** — Called when the outer `PlayErrorBoundary` catches an error. Receives `(error: Error, info: React.ErrorInfo)`. Use for observability tools (Sentry, Datadog, etc.).
+
+**`onRenderError`** — Called when an individual catalog component throws during render. Caught by `@json-render/react`'s inner per-element boundary — 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 (e.g. custom `JSONUIProvider` configuration).
 
 ```tsx
+import { ActorProvider } from "@xmachines/play-react";
+
+<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 output via `PlayErrorBoundary`. 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, info) => Sentry.captureException(err, { extra: info })}
+>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+### Inner boundary — `onRenderError`
+
+Each catalog element is individually wrapped in an error boundary by `@json-render/react`. 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 () => {
-			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` (machine in a no-view state, or during initialisation).
+`onRenderError` is typed as `RenderErrorHandler` and exported from `@xmachines/play-react`.
 
 ---
 
@@ -251,7 +323,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.
 
 ---
 
@@ -278,7 +350,7 @@ function NavBar({ actor }: { actor: ReturnType<typeof createPlayer> }) {
 
 ### `PlayErrorBoundary`
 
-Class error boundary that wraps the rendered output. Catches errors thrown during component render and logs them without crashing the full page. `PlayRenderer` wraps its own output in this boundary automatically.
+Class error boundary that wraps the rendered output. `PlayRenderer` wraps its own output in this boundary automatically — use this directly only if you need to wrap other content or nest boundaries manually.
 
 `componentDidCatch` invokes the `onError` prop (for observability tools) but does **not** re-throw — re-throwing from `componentDidCatch` can unmount the entire React 19 root. `getDerivedStateFromError` handles fallback state transition instead.
 
@@ -289,7 +361,9 @@ import { PlayErrorBoundary } from "@xmachines/play-react";
 	fallback={<p>Something went wrong.</p>}
 	onError={(err, info) => Sentry.captureException(err, { extra: info })}
 >
-	<PlayRenderer actor={actor} registryResult={registryResult} />
+	<PlayUIProvider actor={actor} registryResult={registryResult}>
+		<PlayRenderer />
+	</PlayUIProvider>
 </PlayErrorBoundary>;
 ```
 
@@ -311,10 +385,10 @@ Priority: **route param fills `undefined` slots; explicit non-`undefined` spec p
 
 ## Error Handling
 
-| Error                                             | Cause                        | Fix                                                              |
-| ------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
-| `useActor() must be called inside <PlayRenderer>` | Hook called outside the tree | Move inside a component rendered by `PlayRenderer`               |
-| Component render error                            | Component throws             | `PlayErrorBoundary` catches it; inspect component implementation |
+| Error                                                                    | Cause                        | Fix                                                              |
+| ------------------------------------------------------------------------ | ---------------------------- | ---------------------------------------------------------------- |
+| `useActor() must be called inside <ActorProvider> (or <PlayUIProvider>)` | Hook called outside the tree | Wrap with `<PlayUIProvider>` or `<ActorProvider>`                |
+| Component render error                                                   | Component throws             | `PlayErrorBoundary` catches it; inspect component implementation |
 
 ---
 
@@ -327,7 +401,7 @@ Priority: **route param fills `undefined` slots; explicit non-`undefined` spec p
 
 @xmachines/play-react - React renderer for XMachines Play architecture
 
-Provides a thin React rendering layer that passively observes actor signals
+Provides a provider-based React rendering layer that passively observes actor signals
 and renders UI components via @json-render/react. This package enables
 framework-swappable architecture where React is just a rendering target
 that subscribes to signal changes.
@@ -335,9 +409,23 @@ that subscribes to signal changes.
 **Key principle:** React state is NEVER used for business logic—only for
 triggering React's render cycle. Signals are the source of truth.
 
-Re-exports `defineRegistry`, `useBoundProp`, `ComponentFn`, and
-`ComponentContext` from `@json-render/react` so consumers import everything
-from `@xmachines/play-react` rather than `@json-render/react` directly.
+**Standard usage:**
+
+```tsx
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+**Escape hatch (custom composition):**
+
+```tsx
+<ActorProvider actor={actor} registryResult={registryResult}>
+	<JSONUIProvider registry={registryResult.registry}>
+		<PlayRenderer />
+	</JSONUIProvider>
+</ActorProvider>
+```
 
 ## Classes
 
@@ -345,10 +433,18 @@ from `@xmachines/play-react` rather than `@json-render/react` directly.
 
 ## Interfaces
 
+- [ActionProviderProps](interfaces/ActionProviderProps.md)
+- [ActorProviderProps](interfaces/ActorProviderProps.md)
 - [ComponentContext](interfaces/ComponentContext.md)
+- [JSONUIProviderProps](interfaces/JSONUIProviderProps.md)
 - [PlayErrorBoundaryProps](interfaces/PlayErrorBoundaryProps.md)
 - [PlayErrorBoundaryState](interfaces/PlayErrorBoundaryState.md)
-- [PlayRendererProps](interfaces/PlayRendererProps.md)
+- [PlayUIProviderProps](interfaces/PlayUIProviderProps.md)
+- [RendererProps](interfaces/RendererProps.md)
+- [StateProviderProps](interfaces/StateProviderProps.md)
+- [ValidationProviderProps](interfaces/ValidationProviderProps.md)
+- [ViewContextValue](interfaces/ViewContextValue.md)
+- [VisibilityProviderProps](interfaces/VisibilityProviderProps.md)
 
 ## Type Aliases
 
@@ -358,11 +454,32 @@ from `@xmachines/play-react` rather than `@json-render/react` directly.
 
 ## Variables
 
+- [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)
 - [useActor](functions/useActor.md)
 - [useBoundProp](functions/useBoundProp.md)
+- [usePlayView](functions/usePlayView.md)
 - [useSignalEffect](functions/useSignalEffect.md)
+- [ValidationProvider](functions/ValidationProvider.md)
+- [VisibilityProvider](functions/VisibilityProvider.md)
+
+## References
+
+### PlayRendererProps
+
+Renames and re-exports [ActorProviderProps](interfaces/ActorProviderProps.md)
+
+---
+
+### RenderErrorHandler
+
+Re-exports [RenderErrorHandler](type-aliases/RenderErrorHandler.md)

package/api/@xmachines/play-react/classes/PlayErrorBoundary.md

@@ -2,7 +2,7 @@
 
 # Class: PlayErrorBoundary
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/PlayErrorBoundary.tsx#L53)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/PlayErrorBoundary.tsx#L53)
 
 React class component error boundary for catching catalog component render errors.
 
@@ -36,7 +36,7 @@ Per CONS-14: Class component pattern works with all React versions (18 and 19).
 new PlayErrorBoundary(props): PlayErrorBoundary;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/PlayErrorBoundary.tsx#L57)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/PlayErrorBoundary.tsx#L57)
 
 #### Parameters
 
@@ -75,7 +75,7 @@ React.Component<
 componentDidCatch(error, info): void;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/PlayErrorBoundary.tsx#L66)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/PlayErrorBoundary.tsx#L66)
 
 Catches exceptions generated in descendant components. Unhandled exceptions will cause
 the entire component tree to unmount.
@@ -375,7 +375,7 @@ React.Component.getSnapshotBeforeUpdate;
 render(): ReactNode;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/PlayErrorBoundary.tsx#L70)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/PlayErrorBoundary.tsx#L70)
 
 #### Returns
 
@@ -604,7 +604,7 @@ React.Component.UNSAFE_componentWillUpdate;
 static getDerivedStateFromError(error): PlayErrorBoundaryState;
 ```
 
-Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/PlayErrorBoundary.tsx#L62)
+Defined in: [packages/play-react/src/PlayErrorBoundary.tsx:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/PlayErrorBoundary.tsx#L62)
 
 #### Parameters
 

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

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / ActionProvider
+
+# Function: ActionProvider()
+
+```ts
+function ActionProvider(__namedParameters): Element;
+```
+
+Defined in: `@json-render/react`
+
+Provider for action execution
+
+## Parameters
+
+| Parameter           | Type                                                          |
+| ------------------- | ------------------------------------------------------------- |
+| `__namedParameters` | [`ActionProviderProps`](../interfaces/ActionProviderProps.md) |
+
+## Returns
+
+`Element`

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

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

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

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

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

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / StateProvider
+
+# Function: StateProvider()
+
+```ts
+function StateProvider(__namedParameters): Element;
+```
+
+Defined in: `@json-render/react`
+
+Provider for state model context.
+
+Supports two modes:
+
+- **Controlled**: pass a `store` prop (e.g. backed by Redux / Zustand).
+- **Uncontrolled** (default): omit `store` and optionally pass
+  `initialState` / `onStateChange`.
+
+## Parameters
+
+| Parameter           | Type                                                        |
+| ------------------- | ----------------------------------------------------------- |
+| `__namedParameters` | [`StateProviderProps`](../interfaces/StateProviderProps.md) |
+
+## Returns
+
+`Element`

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

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / ValidationProvider
+
+# Function: ValidationProvider()
+
+```ts
+function ValidationProvider(__namedParameters): Element;
+```
+
+Defined in: `@json-render/react`
+
+Provider for validation
+
+## Parameters
+
+| Parameter           | Type                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `__namedParameters` | [`ValidationProviderProps`](../interfaces/ValidationProviderProps.md) |
+
+## Returns
+
+`Element`

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

@@ -0,0 +1,21 @@
+[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / VisibilityProvider
+
+# Function: VisibilityProvider()
+
+```ts
+function VisibilityProvider(__namedParameters): Element;
+```
+
+Defined in: `@json-render/react`
+
+Provider for visibility evaluation
+
+## Parameters
+
+| Parameter           | Type                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `__namedParameters` | [`VisibilityProviderProps`](../interfaces/VisibilityProviderProps.md) |
+
+## Returns
+
+`Element`

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

@@ -6,7 +6,7 @@
 function useActor(): PlayActor;
 ```
 
-Defined in: [packages/play-react/src/useActor.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/useActor.ts#L30)
+Defined in: [packages/play-react/src/useActor.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/useActor.ts#L31)
 
 ## Returns
 

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

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

package/api/@xmachines/play-react/functions/useSignalEffect.md

@@ -6,7 +6,7 @@
 function useSignalEffect(callback): void;
 ```
 
-Defined in: [packages/play-react/src/useSignalEffect.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/useSignalEffect.ts#L71)
+Defined in: [packages/play-react/src/useSignalEffect.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/useSignalEffect.ts#L71)
 
 React hook that subscribes to signal changes and runs effect callback
 

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

@@ -0,0 +1,15 @@
+[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / ActionProviderProps
+
+# Interface: ActionProviderProps
+
+Defined in: `@json-render/react`
+
+Props for ActionProvider
+
+## Properties
+
+| Property                                   | Type                                  | Description             | Defined in |
+| ------------------------------------------ | ------------------------------------- | ----------------------- | ---------- |
+| <a id="property-children"></a> `children`  | `ReactNode`                           | -                       | -          |
+| <a id="property-handlers"></a> `handlers?` | `Record`\<`string`, `ActionHandler`\> | Initial action handlers | -          |
+| <a id="property-navigate"></a> `navigate?` | (`path`) => `void`                    | Navigation function     | -          |

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

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / ActorProviderProps
+
+# Interface: ActorProviderProps
+
+Defined in: [packages/play-react/src/ActorProvider.tsx:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/ActorProvider.tsx#L31)
+
+Props for the ActorProvider component.
+
+## Extends
+
+- [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md)\<`DefineRegistryResult`\>
+
+## Extended by
+
+- [`PlayUIProviderProps`](PlayUIProviderProps.md)
+
+## Properties
+
+| Property                                              | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                 | Inherited from                                                                                                                                                                      | Defined in                                                                                                                                                       |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability).                                                                                                                                                      | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`actor`](../../play-actor/interfaces/BaseActorProviderProps.md#property-actor)                   | [packages/play-actor/src/abstract-actor.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-actor/src/abstract-actor.ts#L154) |
+| <a id="property-children"></a> `children`             | `ReactNode`                                                                                                                                                                                                                                                      | Child components to render inside the provider tree                                                                                                                                                                         | -                                                                                                                                                                                   | [packages/play-react/src/ActorProvider.tsx:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/ActorProvider.tsx#L37)   |
+| <a id="property-fallback"></a> `fallback?`            | `ReactNode`                                                                                                                                                                                                                                                      | Optional component shown when currentView is null or a catalog component throws                                                                                                                                             | -                                                                                                                                                                                   | [packages/play-react/src/ActorProvider.tsx:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/ActorProvider.tsx#L33)   |
+| <a id="property-onerror"></a> `onError?`              | (`error`, `info`) => `void`                                                                                                                                                                                                                                      | Optional error handler callback invoked when a catalog component throws during render                                                                                                                                       | -                                                                                                                                                                                   | [packages/play-react/src/ActorProvider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-react/src/ActorProvider.tsx#L35)   |
+| <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:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-actor/src/abstract-actor.ts#L167) |
+| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                                                                                           | Full result from defineRegistry() — contains the component registry and action handlers factory.                                                                                                                            | [`BaseActorProviderProps`](../../play-actor/interfaces/BaseActorProviderProps.md).[`registryResult`](../../play-actor/interfaces/BaseActorProviderProps.md#property-registryresult) | [packages/play-actor/src/abstract-actor.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-actor/src/abstract-actor.ts#L156) |
+| <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:162](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-actor/src/abstract-actor.ts#L162) |