@xmachines/play-react 1.0.0-beta.33 → 1.0.0-beta.34

package/README.md

@@ -41,14 +41,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";
@@ -119,12 +124,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: [] },
 						},
 					},
 				},
@@ -134,12 +136,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: [] },
 						},
 					},
 				},
@@ -169,31 +168,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):
 
@@ -207,31 +211,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>;
+```
+
+**`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>;
 ```
 
-**Inner render errors** — You can intercept catalog component render failures without
-overriding the outer `PlayErrorBoundary`:
+---
+
+### `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`.
 
 ---
 
@@ -249,7 +321,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.
 
 ---
 
@@ -276,7 +348,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.
 
@@ -287,7 +359,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>;
 ```
 
@@ -309,10 +383,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 |
 
 ---
 

package/dist/ActorProvider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ActorProvider — escape hatch primitive for actor lifecycle management.
+ *
+ * Owns: actor bridging, signal subscription (useSignalEffect), per-view StateStore
+ * lifecycle (controlled/uncontrolled), handler resolution via inner component pattern
+ * (uses useStateStore()), StateProvider wrap, PlayErrorBoundary wrap, onRenderError injection.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import type { DefineRegistryResult, ComponentRegistry } from "@json-render/react";
+import type { BaseActorProviderProps, BaseViewContextValue } from "@xmachines/play-actor";
+/**
+ * Props for the ActorProvider component.
+ *
+ * @public
+ */
+export interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+    /** Optional component shown when currentView is null or a catalog component throws */
+    fallback?: React.ReactNode;
+    /** Optional error handler callback invoked when a catalog component throws during render */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+    /** Child components to render inside the provider tree */
+    children: React.ReactNode;
+}
+/**
+ * Value provided by ViewContext (accessible via usePlayView()).
+ *
+ * @public
+ */
+export interface ViewContextValue extends BaseViewContextValue<ComponentRegistry> {
+}
+/**
+ * Hook to access the current view spec, handlers, and registry.
+ *
+ * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ *
+ * @throws {Error} 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} />;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function usePlayView(): ViewContextValue;
+/**
+ * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ *
+ * Subscribes to actor.currentView signal, manages the per-view StateStore lifecycle,
+ * wraps children in StateProvider and PlayErrorBoundary, and injects onRenderError
+ * into the component registry.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @example
+ * ```tsx
+ * // Custom composition (escape hatch):
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ *
+ * // Standard usage: prefer PlayUIProvider
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export declare const ActorProvider: React.FC<ActorProviderProps>;
+//# sourceMappingURL=ActorProvider.d.ts.map

package/dist/ActorProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorProvider.d.ts","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAsD,MAAM,OAAO,CAAC;AAE3E,OAAO,KAAK,EAAE,oBAAoB,EAAY,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAO5F,OAAO,KAAK,EAAY,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAIpG;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;IACvF,sFAAsF;IACtF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,4FAA4F;IAC5F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IACxD,0DAA0D;IAC1D,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;CAAG;AAQpF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,gBAAgB,CAE9C;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAqFtD,CAAC"}

package/dist/ActorProvider.js

@@ -0,0 +1,166 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ActorProvider — escape hatch primitive for actor lifecycle management.
+ *
+ * Owns: actor bridging, signal subscription (useSignalEffect), per-view StateStore
+ * lifecycle (controlled/uncontrolled), handler resolution via inner component pattern
+ * (uses useStateStore()), StateProvider wrap, PlayErrorBoundary wrap, onRenderError injection.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @packageDocumentation
+ */
+import React, { useState, useRef, createContext, useContext } from "react";
+import { StateProvider, useStateStore } from "@json-render/react";
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import { useSignalEffect } from "./useSignalEffect.js";
+import { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+import { assertNonNullable } from "@xmachines/play";
+import { ActorContext } from "./useActor.js";
+/**
+ * Internal React context for ViewContextValue.
+ * Accessed via usePlayView() hook.
+ */
+const ViewContext = createContext(null);
+/**
+ * Hook to access the current view spec, handlers, and registry.
+ *
+ * Must be called inside <ActorProvider> or <PlayUIProvider>.
+ *
+ * @throws {Error} 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} />;
+ * }
+ * ```
+ *
+ * @public
+ */
+export function usePlayView() {
+    return assertNonNullable(useContext(ViewContext), "ViewContext");
+}
+/**
+ * Create a StateStore backed by a fresh @xstate/store atom seeded from the given state.
+ * Called internally per view transition when no external store prop is provided.
+ */
+function createViewStore(initialState) {
+    return xstateStoreStateStore({ atom: createAtom(initialState) });
+}
+/**
+ * Inner component that runs inside StateProvider so it can access StateStore context
+ * via useStateStore(). Resolves action handlers from registryResult.handlers() using
+ * the live StateProvider set/getSnapshot functions, then exposes them via ViewContext.
+ */
+function ActorProviderInner({ registryResult, spec, store, children, }) {
+    const stateCtx = useStateStore();
+    // Build a SetState adapter: the handlers factory expects an updater-function pattern
+    // ((prev) => next), while stateCtx provides path-based set/update. This adapter
+    // bridges the two so action functions can use setState if needed.
+    const setStateAdapter = (updater) => {
+        const prev = stateCtx.getSnapshot();
+        stateCtx.update(updater(prev));
+    };
+    const handlers = registryResult.handlers(() => setStateAdapter, () => stateCtx.getSnapshot());
+    const viewValue = {
+        spec,
+        handlers,
+        registry: registryResult.registry,
+        store,
+    };
+    return _jsx(ViewContext.Provider, { value: viewValue, children: children });
+}
+/**
+ * ActorProvider — escape hatch primitive for composing actor lifecycle with custom providers.
+ *
+ * Subscribes to actor.currentView signal, manages the per-view StateStore lifecycle,
+ * wraps children in StateProvider and PlayErrorBoundary, and injects onRenderError
+ * into the component registry.
+ *
+ * Standard usage: prefer <PlayUIProvider> unless you need to compose providers manually.
+ *
+ * @example
+ * ```tsx
+ * // Custom composition (escape hatch):
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ *
+ * // Standard usage: prefer PlayUIProvider
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export const ActorProvider = ({ actor, registryResult, store: externalStore, fallback = null, onError, onRenderError, children, }) => {
+    // React state for triggering re-renders (NOT business logic state)
+    // Signal is source of truth, useState is just React's render trigger
+    const [view, setView] = useState(() => actor.currentView.get());
+    // Internal store ref — tracks the current per-view atom store.
+    // Keyed to view identity: recreated whenever the view changes (new spec.state seed).
+    // Ignored when externalStore is provided.
+    const internalStoreRef = useRef(null);
+    const lastViewRef = useRef(null);
+    // Subscribe to signal changes
+    useSignalEffect(() => {
+        const currentView = actor.currentView.get();
+        setView(currentView);
+    });
+    // Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level handler)
+    // Centralised here per D-19 — one location for all framework renderers
+    const activeRegistryResult = onRenderError
+        ? {
+            ...registryResult,
+            registry: (() => {
+                const r = { ...registryResult.registry };
+                Object.defineProperty(r, "onRenderError", {
+                    value: onRenderError,
+                    enumerable: false,
+                    configurable: true,
+                });
+                return r;
+            })(),
+        }
+        : registryResult;
+    // No view in current state — render fallback
+    if (!view) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    // Resolve the store to use for StateProvider:
+    // - External (controlled): use as-is, caller manages lifecycle
+    // - Internal: create a fresh atom when the view changes (new route/state)
+    let store;
+    if (externalStore) {
+        store = externalStore;
+    }
+    else {
+        // Recreate the internal store when the view identity changes
+        // (view is a new object on every transition per deriveCurrentView)
+        if (internalStoreRef.current === null || lastViewRef.current !== view) {
+            // Proto-safe guard (T-37-03-01): prevents Date/Array/class-instance from being
+            // passed to createAtom. Replaces the weak `?? {}` guard from old code_context.
+            const rawState = view.state;
+            const initialState = rawState !== null &&
+                rawState !== undefined &&
+                typeof rawState === "object" &&
+                !Array.isArray(rawState) &&
+                Object.getPrototypeOf(rawState) === Object.prototype
+                ? rawState
+                : {};
+            internalStoreRef.current = createViewStore(initialState);
+            lastViewRef.current = view;
+        }
+        store = internalStoreRef.current;
+    }
+    return (_jsx(ActorContext.Provider, { value: actor, children: _jsx(PlayErrorBoundary, { fallback: fallback, ...(onError && { onError }), children: _jsx(StateProvider, { store: store, children: _jsx(ActorProviderInner, { registryResult: activeRegistryResult, spec: view, store: store, children: children }) }) }) }));
+};
+//# sourceMappingURL=ActorProvider.js.map

package/dist/ActorProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorProvider.js","sourceRoot":"","sources":["../src/ActorProvider.tsx"],"names":[],"mappings":"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"}

package/dist/PlayRenderer.d.ts

@@ -1,55 +1,36 @@
 /**
- * PlayRenderer - Main React renderer component for XMachines Play architecture
+ * PlayRenderer — zero-prop leaf component for rendering the current actor view.
  *
- * Backed by @json-render/react for spec-driven UI rendering.
+ * Must be rendered inside <ActorProvider> or <PlayUIProvider>.
+ * Reads view spec, handlers, and registry from usePlayView() context,
+ * then delegates to @json-render/react Renderer.
+ *
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * For custom provider composition, use <ActorProvider> (escape hatch):
+ * ```tsx
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ * ```
  *
  * @packageDocumentation
  */
 import React from "react";
-import type { PlayRendererProps } from "./types.js";
 /**
- * Main renderer component that subscribes to actor signals and renders UI
- * via @json-render/react Renderer.
- *
- * Architecture:
- * - Subscribes to actor.currentView signal via useSignalEffect
- * - Renders view.spec via StateProvider → ActionProvider → VisibilityProvider → Renderer
- * - Routes actions via registryResult.handlers() — real async functions dispatching to actor.
- * - State store: uses external `store` prop if provided (controlled mode); otherwise
- *   creates a fresh @xstate/store atom per view transition seeded from spec.state.
- *   The atom resets automatically when the actor transitions to a new view, mirroring
- *   the actor's currentView lifecycle.
+ * Zero-prop leaf component that renders the current actor view.
  *
- * Invariant: Actor Authority - Actor decides all state transitions via guards.
- * Invariant: Passive Infrastructure - Component observes signals and sends events.
- * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
- *
- * @example
- * ```typescript
- * import { PlayRenderer } from "@xmachines/play-react";
- * import { defineRegistry } from "@json-render/react";
- *
- * const registryResult = defineRegistry(catalog, {
- *   components: { Login, Dashboard },
- *   actions: {
- *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
- *     logout: async () => actor.send({ type: 'auth.logout' }),
- *     route: async ({ to, params }) => actor.send({ type: 'play.route', to, params }),
- *   },
- * });
- *
- * // Uncontrolled — fresh atom created per view, seeded from spec.state:
- * <PlayRenderer actor={actor} registryResult={registryResult} />
- *
- * // Controlled — caller provides and owns the store:
- * import { createAtom } from "@xstate/store";
- * import { xstateStoreStateStore } from "@json-render/xstate";
- * const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
- * <PlayRenderer actor={actor} registryResult={registryResult} store={store} />
- * ```
+ * Reads the current PlaySpec, handlers, and registry from the ActorProvider
+ * context via usePlayView(), then renders via @json-render/react Renderer.
  *
- * @param props - Component props
- * @returns React element rendering current view from actor
+ * @public
  */
-export declare const PlayRenderer: React.FC<PlayRendererProps>;
+export declare const PlayRenderer: React.FC;
 //# sourceMappingURL=PlayRenderer.d.ts.map

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAA2B,MAAM,OAAO,CAAC;AAchD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiDpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA2EpD,CAAC"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAGhC,CAAC"}

package/dist/PlayRenderer.js

@@ -1,136 +1,42 @@
-import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
- * PlayRenderer - Main React renderer component for XMachines Play architecture
+ * PlayRenderer — zero-prop leaf component for rendering the current actor view.
  *
- * Backed by @json-render/react for spec-driven UI rendering.
+ * Must be rendered inside <ActorProvider> or <PlayUIProvider>.
+ * Reads view spec, handlers, and registry from usePlayView() context,
+ * then delegates to @json-render/react Renderer.
+ *
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * For custom provider composition, use <ActorProvider> (escape hatch):
+ * ```tsx
+ * <ActorProvider actor={actor} registryResult={registryResult}>
+ *   <JSONUIProvider registry={registryResult.registry}>
+ *     <PlayRenderer />
+ *   </JSONUIProvider>
+ * </ActorProvider>
+ * ```
  *
  * @packageDocumentation
  */
-import React, { useState, useRef } from "react";
-import { Renderer, StateProvider, ActionProvider, VisibilityProvider, useStateStore, } from "@json-render/react";
-import { createAtom } from "@xstate/store";
-import { xstateStoreStateStore } from "@json-render/xstate";
-import { useSignalEffect } from "./useSignalEffect.js";
-import { PlayErrorBoundary } from "./PlayErrorBoundary.js";
-import { ActorContext } from "./useActor.js";
-/**
- * Create a StateStore backed by a fresh @xstate/store atom seeded from the given state.
- * Called internally per view transition when no external store prop is provided.
- */
-function createViewStore(initialState) {
-    return xstateStoreStateStore({ atom: createAtom(initialState) });
-}
-/**
- * Inner component that runs inside StateProvider so it can access StateStore context
- * via useStateStore(). Resolves action handlers from registryResult.handlers() using
- * the live StateProvider set/getSnapshot functions, then renders ActionProvider.
- */
-function PlayRendererInner({ registryResult, spec, }) {
-    const stateCtx = useStateStore();
-    // Build a SetState adapter: the handlers factory expects an updater-function pattern
-    // ((prev) => next), while stateCtx provides path-based set/update. This adapter
-    // bridges the two so action functions can use setState if needed.
-    const setStateAdapter = (updater) => {
-        const prev = stateCtx.getSnapshot();
-        stateCtx.update(updater(prev));
-    };
-    const handlers = registryResult.handlers(() => setStateAdapter, () => stateCtx.getSnapshot());
-    return (_jsx(ActionProvider, { handlers: handlers, children: _jsx(VisibilityProvider, { children: _jsx(Renderer, { spec: spec, registry: registryResult.registry }) }) }));
-}
+import React from "react";
+import { Renderer } from "@json-render/react";
+import { usePlayView } from "./ActorProvider.js";
 /**
- * Main renderer component that subscribes to actor signals and renders UI
- * via @json-render/react Renderer.
- *
- * Architecture:
- * - Subscribes to actor.currentView signal via useSignalEffect
- * - Renders view.spec via StateProvider → ActionProvider → VisibilityProvider → Renderer
- * - Routes actions via registryResult.handlers() — real async functions dispatching to actor.
- * - State store: uses external `store` prop if provided (controlled mode); otherwise
- *   creates a fresh @xstate/store atom per view transition seeded from spec.state.
- *   The atom resets automatically when the actor transitions to a new view, mirroring
- *   the actor's currentView lifecycle.
- *
- * Invariant: Actor Authority - Actor decides all state transitions via guards.
- * Invariant: Passive Infrastructure - Component observes signals and sends events.
- * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
- *
- * @example
- * ```typescript
- * import { PlayRenderer } from "@xmachines/play-react";
- * import { defineRegistry } from "@json-render/react";
+ * Zero-prop leaf component that renders the current actor view.
  *
- * const registryResult = defineRegistry(catalog, {
- *   components: { Login, Dashboard },
- *   actions: {
- *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
- *     logout: async () => actor.send({ type: 'auth.logout' }),
- *     route: async ({ to, params }) => actor.send({ type: 'play.route', to, params }),
- *   },
- * });
- *
- * // Uncontrolled — fresh atom created per view, seeded from spec.state:
- * <PlayRenderer actor={actor} registryResult={registryResult} />
- *
- * // Controlled — caller provides and owns the store:
- * import { createAtom } from "@xstate/store";
- * import { xstateStoreStateStore } from "@json-render/xstate";
- * const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
- * <PlayRenderer actor={actor} registryResult={registryResult} store={store} />
- * ```
+ * Reads the current PlaySpec, handlers, and registry from the ActorProvider
+ * context via usePlayView(), then renders via @json-render/react Renderer.
  *
- * @param props - Component props
- * @returns React element rendering current view from actor
+ * @public
  */
-export const PlayRenderer = ({ actor, registryResult, store: externalStore, fallback = null, onError, onRenderError, }) => {
-    // React state for triggering re-renders (NOT business logic state)
-    // Signal is source of truth, useState is just React's render trigger
-    const [view, setView] = useState(() => actor.currentView.get());
-    // Internal store ref — tracks the current per-view atom store.
-    // Keyed to view identity: recreated whenever the view changes (new spec.state seed).
-    // Ignored when externalStore is provided.
-    const internalStoreRef = useRef(null);
-    const lastViewRef = useRef(null);
-    // Subscribe to signal changes
-    useSignalEffect(() => {
-        const currentView = actor.currentView.get();
-        setView(currentView);
-    });
-    // No view in current state — render fallback
-    if (!view) {
-        return _jsx(_Fragment, { children: fallback });
-    }
-    // Inject onRenderError prop into registry (non-enumerable, overrides defineRegistry-level handler)
-    const activeRegistryResult = onRenderError
-        ? {
-            ...registryResult,
-            registry: (() => {
-                const r = { ...registryResult.registry };
-                Object.defineProperty(r, "onRenderError", {
-                    value: onRenderError,
-                    enumerable: false,
-                    configurable: true,
-                });
-                return r;
-            })(),
-        }
-        : registryResult;
-    // Resolve the store to use for StateProvider:
-    // - External (controlled): use as-is, caller manages lifecycle
-    // - Internal: create a fresh atom when the view changes (new route/state)
-    let store;
-    if (externalStore) {
-        store = externalStore;
-    }
-    else {
-        // Recreate the internal store when the view identity changes
-        // (view is a new object on every transition per deriveCurrentView)
-        if (internalStoreRef.current === null || lastViewRef.current !== view) {
-            const initialState = view.spec?.state ?? {};
-            internalStoreRef.current = createViewStore(initialState);
-            lastViewRef.current = view;
-        }
-        store = internalStoreRef.current;
-    }
-    return (_jsx(ActorContext.Provider, { value: actor, children: _jsx(PlayErrorBoundary, { fallback: fallback, ...(onError && { onError }), children: _jsx(StateProvider, { store: store, children: _jsx(PlayRendererInner, { registryResult: activeRegistryResult, spec: view.spec ?? null }) }) }) }));
+export const PlayRenderer = () => {
+    const view = usePlayView();
+    return _jsx(Renderer, { spec: view.spec, registry: view.registry });
 };
 //# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAa,GAAG,EAAE;IAC1C,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,OAAO,KAAC,QAAQ,IAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,GAAI,CAAC;AAC/D,CAAC,CAAC"}

package/dist/PlayUIProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PlayUIProvider — batteries-included composite provider for actor-driven UI rendering.
+ *
+ * Wraps ActorProvider + JSONUIProvider (from @json-render/react) to provide a single
+ * entry point for all actor lifecycle and UI rendering concerns.
+ *
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * For custom provider composition (escape hatch), use <ActorProvider> directly.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import { type JSONUIProviderProps } from "@json-render/react";
+import { type ActorProviderProps } from "./ActorProvider.js";
+type JSONUIForwardedProps = Pick<JSONUIProviderProps, "validationFunctions" | "navigate" | "functions">;
+/**
+ * Props for PlayUIProvider — all ActorProvider props plus JSONUIProvider's own props.
+ *
+ * @public
+ */
+export interface PlayUIProviderProps extends ActorProviderProps, Partial<JSONUIForwardedProps> {
+}
+/**
+ * PlayUIProvider — batteries-included entry point for actor-driven UI rendering.
+ *
+ * Combines actor lifecycle management (ActorProvider) with full UI provider setup
+ * (JSONUIProvider including ActionProvider, ValidationProvider, VisibilityProvider,
+ * StateProvider, and ConfirmDialogManager).
+ *
+ * @example
+ * ```tsx
+ * import { PlayUIProvider, PlayRenderer } from "@xmachines/play-react";
+ *
+ * const registryResult = defineRegistry(catalog, {
+ *   components: { Login, Dashboard },
+ *   actions: {
+ *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+ *     logout: async () => actor.send({ type: 'auth.logout' }),
+ *   },
+ * });
+ *
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ *
+ * // With JSONUIProvider options:
+ * <PlayUIProvider
+ *   actor={actor}
+ *   registryResult={registryResult}
+ *   navigate={(path) => router.push(path)}
+ *   validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
+ * >
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export declare const PlayUIProvider: React.FC<PlayUIProviderProps>;
+export {};
+//# sourceMappingURL=PlayUIProvider.d.ts.map

package/dist/PlayUIProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayUIProvider.d.ts","sourceRoot":"","sources":["../src/PlayUIProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGzF,KAAK,oBAAoB,GAAG,IAAI,CAC/B,mBAAmB,EACnB,qBAAqB,GAAG,UAAU,GAAG,WAAW,CAChD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB,EAAE,OAAO,CAAC,oBAAoB,CAAC;CAAG;AAgCjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAiBxD,CAAC"}

package/dist/PlayUIProvider.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * PlayUIProvider — batteries-included composite provider for actor-driven UI rendering.
+ *
+ * Wraps ActorProvider + JSONUIProvider (from @json-render/react) to provide a single
+ * entry point for all actor lifecycle and UI rendering concerns.
+ *
+ * Standard usage:
+ * ```tsx
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * For custom provider composition (escape hatch), use <ActorProvider> directly.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import { JSONUIProvider } from "@json-render/react";
+import { ActorProvider, usePlayView } from "./ActorProvider.js";
+/**
+ * Inner bridge component — reads ViewContext (usePlayView) to get the resolved handlers,
+ * registry, and store, then passes them to JSONUIProvider. The store is passed explicitly
+ * so JSONUIProvider's internal StateProvider uses the same store ActorProvider set up —
+ * without this, JSONUIProvider would create a fresh empty store, shadowing the seeded one.
+ *
+ * Must be inside ActorProvider's tree so usePlayView() has access to ViewContextValue.
+ */
+function JSONUIBridge({ validationFunctions, navigate, functions, children, }) {
+    const view = usePlayView();
+    return (_jsx(JSONUIProvider, { registry: view.registry, handlers: view.handlers, store: view.store, ...(validationFunctions && { validationFunctions }), ...(navigate && { navigate }), ...(functions && { functions }), children: children }));
+}
+/**
+ * PlayUIProvider — batteries-included entry point for actor-driven UI rendering.
+ *
+ * Combines actor lifecycle management (ActorProvider) with full UI provider setup
+ * (JSONUIProvider including ActionProvider, ValidationProvider, VisibilityProvider,
+ * StateProvider, and ConfirmDialogManager).
+ *
+ * @example
+ * ```tsx
+ * import { PlayUIProvider, PlayRenderer } from "@xmachines/play-react";
+ *
+ * const registryResult = defineRegistry(catalog, {
+ *   components: { Login, Dashboard },
+ *   actions: {
+ *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+ *     logout: async () => actor.send({ type: 'auth.logout' }),
+ *   },
+ * });
+ *
+ * <PlayUIProvider actor={actor} registryResult={registryResult}>
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ *
+ * // With JSONUIProvider options:
+ * <PlayUIProvider
+ *   actor={actor}
+ *   registryResult={registryResult}
+ *   navigate={(path) => router.push(path)}
+ *   validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
+ * >
+ *   <PlayRenderer />
+ * </PlayUIProvider>
+ * ```
+ *
+ * @public
+ */
+export const PlayUIProvider = ({ validationFunctions, navigate, functions, ...actorProps }) => {
+    return (_jsx(ActorProvider, { ...actorProps, children: _jsx(JSONUIBridge, { ...(validationFunctions && { validationFunctions }), ...(navigate && { navigate }), ...(functions && { functions }), children: actorProps.children }) }));
+};
+//# sourceMappingURL=PlayUIProvider.js.map

package/dist/PlayUIProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayUIProvider.js","sourceRoot":"","sources":["../src/PlayUIProvider.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,cAAc,EAA4B,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,WAAW,EAA2B,MAAM,oBAAoB,CAAC;AAezF;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,EACrB,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,QAAQ,GACuD;IAC/D,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAE3B,OAAO,CACN,KAAC,cAAc,IACd,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,EACvB,KAAK,EAAE,IAAI,CAAC,KAAK,KACb,CAAC,mBAAmB,IAAI,EAAE,mBAAmB,EAAE,CAAC,KAChD,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,CAAC,KAC1B,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,YAE/B,QAAQ,GACO,CACjB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkC,CAAC,EAC7D,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,GAAG,UAAU,EACb,EAAE,EAAE;IACJ,OAAO,CACN,KAAC,aAAa,OAAK,UAAU,YAC5B,KAAC,YAAY,OACR,CAAC,mBAAmB,IAAI,EAAE,mBAAmB,EAAE,CAAC,KAChD,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,CAAC,KAC1B,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,YAE/B,UAAU,CAAC,QAAQ,GACN,GACA,CAChB,CAAC;AACH,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @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.
@@ -9,20 +9,38 @@
  * **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>
+ * ```
  *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 export { PlayRenderer } from "./PlayRenderer.js";
+export { ActorProvider } from "./ActorProvider.js";
+export type { ActorProviderProps, ViewContextValue } from "./ActorProvider.js";
+export { usePlayView } from "./ActorProvider.js";
+export { PlayUIProvider } from "./PlayUIProvider.js";
+export type { PlayUIProviderProps } from "./PlayUIProvider.js";
 export { useSignalEffect } from "./useSignalEffect.js";
 export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
 export { useActor } from "./useActor.js";
-export { defineRegistry, useBoundProp } from "@json-render/react";
-export type { ComponentFn, ComponentContext } from "@json-render/react";
-export type { PlayRendererProps, RenderErrorHandler } from "./types.js";
-export type { PlayErrorBoundaryProps, PlayErrorBoundaryState } from "./PlayErrorBoundary.js";
 export type { PlayActor } from "./useActor.js";
+export { defineRegistry, useBoundProp, JSONUIProvider, StateProvider, ActionProvider, VisibilityProvider, ValidationProvider, Renderer, } from "@json-render/react";
+export type { ComponentFn, ComponentContext, JSONUIProviderProps, StateProviderProps, ActionProviderProps, VisibilityProviderProps, ValidationProviderProps, RendererProps, } from "@json-render/react";
+export type { ActorProviderProps as PlayRendererProps } from "./ActorProvider.js";
+export type { RenderErrorHandler } from "./types.js";
+export type { PlayErrorBoundaryProps, PlayErrorBoundaryState } from "./PlayErrorBoundary.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EACN,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,GACR,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,GACb,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,kBAAkB,IAAI,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClF,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 /**
  * @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.
@@ -9,19 +9,33 @@
  * **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>
+ * ```
  *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 // Main exports
 export { PlayRenderer } from "./PlayRenderer.js";
+export { ActorProvider } from "./ActorProvider.js";
+export { usePlayView } from "./ActorProvider.js";
+export { PlayUIProvider } from "./PlayUIProvider.js";
 export { useSignalEffect } from "./useSignalEffect.js";
 export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
 export { useActor } from "./useActor.js";
-// Re-export from @json-render/react so consumers import everything from @xmachines/play-react.
-// React's useContext works anywhere in the call tree — no wrapper needed.
-export { defineRegistry, useBoundProp } from "@json-render/react";
+// Re-exports from @json-render/react (per D-14)
+export { defineRegistry, useBoundProp, JSONUIProvider, StateProvider, ActionProvider, VisibilityProvider, ValidationProvider, Renderer, } from "@json-render/react";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,+FAA+F;AAC/F,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,gDAAgD;AAChD,OAAO,EACN,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,QAAQ,GACR,MAAM,oBAAoB,CAAC"}

package/dist/types.d.ts

@@ -1,80 +1,12 @@
 /**
  * TypeScript type definitions for play-react
  *
- * @packageDocumentation
- */
-import type { DefineRegistryResult, RenderErrorHandler } from "@json-render/react";
-import type { StateStore } from "@json-render/core";
-import type { AbstractActor, Viewable } from "@xmachines/play-actor";
-import type React from "react";
-import type { AnyActorLogic } from "xstate";
-/**
- * Props for PlayRenderer component
+ * PlayRendererProps has been removed — use ActorProviderProps or PlayUIProviderProps instead.
+ * See ActorProvider.tsx and PlayUIProvider.tsx.
  *
- * @typeParam TLogic - The XState actor logic type. Defaults to `AnyActorLogic` for
- *   non-generic usage.
- *
- * @property actor - Actor instance with currentView signal (requires Viewable capability)
- * @property registryResult - Full result from defineRegistry() in @json-render/react.
- *   Contains both the component registry and the action handlers factory. Action handlers
- *   are real async functions dispatching to the actor (not string-mapped event types).
- * @property store - Optional external StateStore (controlled mode).
- * @property fallback - Optional component shown when currentView is null
- * @property onError - Optional callback invoked when a catalog component throws during render.
+ * @packageDocumentation
  */
-export interface PlayRendererProps<TLogic extends AnyActorLogic = AnyActorLogic> {
-    /** Actor instance with currentView signal (requires Viewable capability) */
-    actor: AbstractActor<TLogic> & Viewable;
-    /**
-     * Full result from defineRegistry() — contains component registry and action handlers.
-     * Action handlers are async functions that dispatch to the actor (not string-mapped
-     * event type stubs). Replaces the old `registry` + `actions` prop pair.
-     *
-     * @example
-     * ```tsx
-     * const registryResult = defineRegistry(catalog, {
-     *   components: { Login, Dashboard },
-     *   actions: {
-     *     login: async ({ username }) => actor.send({ type: 'auth.login', username }),
-     *     logout: async () => actor.send({ type: 'auth.logout' }),
-     *   },
-     * });
-     * <PlayRenderer actor={actor} registryResult={registryResult} />
-     * ```
-     */
-    registryResult: DefineRegistryResult;
-    /**
-     * Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate).
-     * When provided, PlayRenderer operates in controlled mode — spec.state is ignored and
-     * this store is the single source of truth for UI state (form values, etc.).
-     * When omitted, a fresh @xstate/store atom is created internally per view transition,
-     * seeded from spec.state.
-     */
-    store?: StateStore;
-    /** Optional component shown when currentView is null or a catalog component throws */
-    fallback?: React.ReactNode;
-    /**
-     * Optional error handler callback invoked when a catalog component throws during render.
-     * Forwarded directly to the internal `PlayErrorBoundary` — use to integrate with
-     * production observability tools (Sentry, Datadog, etc.).
-     *
-     * @example
-     * ```tsx
-     * <PlayRenderer actor={actor} registryResult={registryResult} onError={Sentry.captureException} />
-     * ```
-     */
-    onError?: (error: Error, info: React.ErrorInfo) => void;
-    /**
-     * Called when an individual catalog component throws during render.
-     *
-     * Caught by the inner error boundary inside each rendered element — the failed
-     * component is silently removed while the rest of the spec continues rendering.
-     * Unlike `onError`, this does not receive a reset callback.
-     * Takes precedence over any `onRenderError` set via `defineRegistry`.
-     *
-     * When not provided, `@json-render/react` logs the error to `console.error`.
-     */
-    onRenderError?: RenderErrorHandler;
-}
-export type { RenderErrorHandler };
+export type { ActorProviderProps } from "./ActorProvider.js";
+export type { PlayUIProviderProps } from "./PlayUIProvider.js";
+export type { RenderErrorHandler } from "@json-render/react";
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa;IAC9E,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;IAExC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,EAAE,oBAAoB,CAAC;IAErC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE3B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IAExD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types.js

@@ -1,6 +1,9 @@
 /**
  * TypeScript type definitions for play-react
  *
+ * PlayRendererProps has been removed — use ActorProviderProps or PlayUIProviderProps instead.
+ * See ActorProvider.tsx and PlayUIProvider.tsx.
+ *
  * @packageDocumentation
  */
 export {};

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/useActor.d.ts

@@ -4,7 +4,7 @@
  * Components rendered inside PlayRenderer can call useActor() to get direct
  * access to the actor instance without prop drilling.
  *
- * @throws {Error} If called outside a PlayRenderer tree
+ * @throws {NonNullableError} If called outside an ActorProvider/PlayUIProvider tree
  *
  * @example
  * ```typescript

package/dist/useActor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useActor.d.ts","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAErD,eAAO,MAAM,YAAY,2CAAwC,CAAC;AAElE,wBAAgB,QAAQ,IAAI,SAAS,CAIpC"}
+{"version":3,"file":"useActor.d.ts","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAErD,eAAO,MAAM,YAAY,2CAAwC,CAAC;AAElE,wBAAgB,QAAQ,IAAI,SAAS,CAEpC"}

package/dist/useActor.js

@@ -4,7 +4,7 @@
  * Components rendered inside PlayRenderer can call useActor() to get direct
  * access to the actor instance without prop drilling.
  *
- * @throws {Error} If called outside a PlayRenderer tree
+ * @throws {NonNullableError} If called outside an ActorProvider/PlayUIProvider tree
  *
  * @example
  * ```typescript
@@ -19,11 +19,9 @@
  * @packageDocumentation
  */
 import { createContext, useContext } from "react";
+import { assertNonNullable } from "@xmachines/play";
 export const ActorContext = createContext(null);
 export function useActor() {
-    const actor = useContext(ActorContext);
-    if (!actor)
-        throw new Error("useActor() must be called inside <PlayRenderer>");
-    return actor;
+    return assertNonNullable(useContext(ActorContext), "ActorContext");
 }
 //# sourceMappingURL=useActor.js.map

package/dist/useActor.js.map

@@ -1 +1 @@
-{"version":3,"file":"useActor.js","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAMlD,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAmB,IAAI,CAAC,CAAC;AAElE,MAAM,UAAU,QAAQ;IACvB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC/E,OAAO,KAAK,CAAC;AACd,CAAC"}
+{"version":3,"file":"useActor.js","sourceRoot":"","sources":["../src/useActor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAMpD,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAmB,IAAI,CAAC,CAAC;AAElE,MAAM,UAAU,QAAQ;IACvB,OAAO,iBAAiB,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-react",
-  "version": "1.0.0-beta.33",
+  "version": "1.0.0-beta.34",
   "description": "React renderer for XMachines Play architecture with signal-driven rendering",
   "keywords": [
     "actor",
@@ -45,9 +45,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play": "1.0.0-beta.33",
-    "@xmachines/play-actor": "1.0.0-beta.33",
-    "@xmachines/play-signals": "1.0.0-beta.33"
+    "@xmachines/play": "1.0.0-beta.34",
+    "@xmachines/play-actor": "1.0.0-beta.34",
+    "@xmachines/play-signals": "1.0.0-beta.34"
   },
   "devDependencies": {
     "@json-render/core": "^0.18.0",
@@ -58,7 +58,7 @@
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@xmachines/shared": "1.0.0-beta.33",
+    "@xmachines/shared": "1.0.0-beta.34",
     "@xstate/store": "^3.17.0",
     "jsdom": "^29.0.2",
     "oxfmt": "^0.45.0",