@xmachines/play-react 1.0.0-beta.15 → 1.0.0-beta.17

package/README.md

@@ -1,393 +1,301 @@
 # @xmachines/play-react
 
-**React renderer consuming signals and UI schema with provider pattern**
+**React renderer for XMachines Play Architecture**
 
-Signal-driven React rendering layer observing actor state with zero React state for business logic.
+Bridges TC39 Signal-driven actors to React's render cycle. Business logic stays in the actor; React is purely a rendering target.
 
 ## Overview
 
-`@xmachines/play-react` provides `PlayRenderer` and `useSignalEffect` for building React UIs that passively observe actor signals. This package enables framework-swappable architecture where React is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
+`@xmachines/play-react` provides `PlayRenderer`, a React component that:
 
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+- Subscribes to `actor.currentView` (TC39 Signal) and re-renders on every state transition
+- Renders the current view's JSON spec via `@json-render/react`
+- Routes action names from spec elements to `actor.send()` via the `actions` prop
+- Manages per-view UI state in an `@xstate/store` atom (automatic or caller-supplied)
 
-- **Signal-Only Reactivity (INV-05):** No useState/useReducer for business logic, signals only
-- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md):
 
-**Key Principle:** React state is never used for business logic. Signals are the source of truth.
-
-Renderer receives actor via props (provider pattern), not children.
+- **Actor Authority (INV-01):** Guards in the machine decide all state transitions
+- **Passive Infrastructure (INV-04):** React observes signals and dispatches events — never decides
+- **Signal-Only Reactivity (INV-05):** `actor.currentView` signal is the sole render trigger
 
 ## Installation
 
 ```bash
-npm install react@^18.0.0 react-dom@^18.0.0
 npm install @xmachines/play-react
+npm install @json-render/react @json-render/core   # peer deps
+npm install @json-render/xstate @xstate/store      # store integration
 ```
 
 ## Current Exports
 
-- `PlayRenderer`
-- `useSignalEffect`
-- `PlayErrorBoundary`
+- `PlayRenderer` — main renderer component
+- `useActor` — hook for accessing the actor inside a `PlayRenderer` tree
+- `useSignalEffect` — React hook for subscribing to TC39 Signals
+- `PlayErrorBoundary` — error boundary wrapping renderer output
+- `defineRegistry` — re-exported from `@json-render/react`
+- `useStateBinding` — re-exported from `@json-render/react`
+- `ComponentFn` (type) — re-exported from `@json-render/react`
+- `ComponentContext` (type) — re-exported from `@json-render/react`
 - `PlayRendererProps` (type)
-- `PlayErrorBoundaryProps` (type)
-
-**Peer dependencies:**
-
-- `react` ^18.0.0 || ^19.0.0 — React runtime
-- `react-dom` ^18.0.0 || ^19.0.0 — React DOM renderer
+- `PlayActor` (type)
 
 ## Quick Start
 
-```typescript
-import { createRoot } from "react-dom/client";
-import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
+```tsx
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
 import { PlayRenderer } from "@xmachines/play-react";
+import { defineCatalog } from "@json-render/core";
+import { defineRegistry } from "@xmachines/play-react";
+import type { ComponentFn } from "@xmachines/play-react";
+import { setup, assign } from "xstate";
 import { z } from "zod";
 
-// 1. Define catalog (business logic layer)
+// 1. Define catalog — the contract between machine spec and UI components
 const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({
-		userId: z.string(),
-		username: z.string(),
-	}),
+	elements: {
+		Login: { props: z.object({ title: z.string() }), description: "Login form" },
+		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
+	},
 });
 
-// 2. Create React components (view layer)
-const components = {
-	LoginForm: ({ error, send }) => (
-		<form
-			onSubmit={(e) => {
-				e.preventDefault();
-				const data = new FormData(e.currentTarget);
-				send({
-					type: "auth.login",
-					username: data.get("username"),
-				});
-			}}
-		>
-			{error && <p style={{ color: "red" }}>{error}</p>}
-			<input name="username" required placeholder="Username" />
-			<button type="submit">Log In</button>
-		</form>
-	),
-	Dashboard: ({ userId, username, send }) => (
-		<div>
-			<h1>Welcome, {username}!</h1>
-			<p>User ID: {userId}</p>
-			<button onClick={() => send({ type: "auth.logout" })}>Log Out</button>
-		</div>
-	),
-};
-
-// 3. Create player actor (business logic runtime)
-const createPlayer = definePlayer({ machine: authMachine, catalog });
+// 2. Implement components using ComponentFn — typed against catalog entries
+const Login: ComponentFn<typeof catalog, "Login"> = ({ props, emit }) => (
+	<form
+		onSubmit={(e) => {
+			e.preventDefault();
+			emit("submit");
+		}}
+	>
+		<h2>{props.title}</h2>
+		<button type="submit">Log In</button>
+	</form>
+);
+
+const Dashboard: ComponentFn<typeof catalog, "Dashboard"> = ({ props }) => (
+	<div>Welcome, {props.username}!</div>
+);
+
+// 3. Build registry — wires components to catalog and declares no-op action stubs
+const { registry } = defineRegistry(catalog, {
+	components: { Login, Dashboard },
+	actions: { login: async () => {}, logout: async () => {} },
+});
+
+// 4. Define machine with view metadata
+const machine = setup({
+	types: {
+		context: {} as {
+			isAuthenticated: boolean;
+			username: string | null;
+			routeParams: Record<string, string>;
+			queryParams: Record<string, string>;
+		},
+		events: {} as
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" }
+			| { type: "play.route"; to: string; params?: Record<string, string> },
+	},
+}).createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "login",
+		context: { isAuthenticated: false, username: null, routeParams: {}, queryParams: {} },
+		states: {
+			login: {
+				id: "login",
+				meta: {
+					route: "/login",
+					view: {
+						component: "Login",
+						spec: {
+							root: "root",
+							elements: {
+								root: { type: "Login", props: { title: "Sign In" }, children: [] },
+							},
+						},
+					},
+				},
+			},
+			dashboard: {
+				id: "dashboard",
+				meta: {
+					route: "/dashboard",
+					view: {
+						component: "Dashboard",
+						spec: {
+							root: "root",
+							elements: {
+								root: { type: "Dashboard", props: { username: "" }, children: [] },
+							},
+						},
+					},
+				},
+			},
+		},
+		on: {
+			"auth.login": {
+				target: ".dashboard",
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: assign({
+					isAuthenticated: true,
+					username: ({ event }) => event.username,
+				}),
+			},
+			"auth.logout": {
+				target: ".login",
+				guard: ({ context }) => context.isAuthenticated,
+				actions: assign({ isAuthenticated: false, username: null }),
+			},
+		},
+	}),
+);
+
+// 5. Create actor and render
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start();
 
-// 4. Render UI (actor via props)
-const root = createRoot(document.getElementById("app")!);
-root.render(<PlayRenderer actor={actor} components={components} />);
+function App() {
+	return (
+		<PlayRenderer
+			actor={actor}
+			registry={registry}
+			actions={{ login: "auth.login", logout: "auth.logout" }}
+		/>
+	);
+}
 ```
 
 ## API Reference
 
-### PlayRenderer
+### `PlayRenderer`
 
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+Main component. Subscribes to `actor.currentView` and renders the spec.
 
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<AnyActorLogic> & Viewable;
-	components: Record<string, React.ElementType>;
-	fallback?: React.ReactNode;
-}
+```tsx
+<PlayRenderer
+	actor={actor} // required
+	registry={registry} // required
+	actions={{ login: "auth.login" }} // optional
+	store={myStore} // optional — controlled mode
+	fallback={<p>Loading…</p>} // optional
+/>
 ```
 
-**Props:**
-
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to React components
-- `fallback` - Component shown when `currentView` is null (default: `null`)
-
-**Behavior:**
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-1. Subscribes to `actor.currentView` signal via `useSignalEffect`
-2. Looks up component from `components` map using `view.component` string
-3. Renders component with props from `view.props` + `send` function
+**`registry`** — Built with `defineRegistry(catalog, { components, actions })` from `@xmachines/play-react`.
 
-**Example:**
+**`actions`** — Maps json-render action names (from spec `on` bindings) to XState event type strings. Values are type-checked against `EventFromLogic<TLogic>["type"]` when `TLogic` is specified:
 
-```typescript
-<PlayRenderer
+```tsx
+// Typed: "bad.event" causes a compile error if it is not in the machine's event union
+<PlayRenderer<typeof machine>
 	actor={actor}
-	components={{
-		HomePage: ({ send }) => <div>Home</div>,
-		AboutPage: ({ send }) => <div>About</div>,
-	}}
-	fallback={<div>Loading...</div>}
+	registry={registry}
+	actions={{ login: "auth.login", logout: "auth.logout" }}
 />
 ```
 
-### useSignalEffect()
-
-Hook for subscribing to signal changes with automatic cleanup:
-
-```typescript
-useSignalEffect(() => {
-	const value = signal.get();
-	// React re-renders when signal changes
-});
-```
-
-**Behavior:**
-
-- Tracks signal dependencies automatically via `Signal.Computed` wrapper
-- Uses `Signal.subtle.Watcher` with microtask batching
-- Triggers React state update to force re-render
-- Cleans up watcher on unmount with explicit `unwatch`
-
-**Canonical watcher lifecycle:**
-
-1. `notify`
-2. `queueMicrotask`
-3. drain pending work (`getPending` and/or `Computed.get`)
-4. run effect + trigger render
-5. re-arm watcher via `watch()`
+**`store`** (optional) — Controls per-view UI state (form values, `$state` bindings):
 
-Watcher notification is one-shot, so re-arm and explicit cleanup are both required.
+- **Omitted (uncontrolled, default):** A fresh `@xstate/store` atom is created per view transition, seeded from `view.spec.state`. The atom resets automatically on each state transition.
+- **Provided (controlled):** The caller owns the store lifecycle. `spec.state` is ignored.
 
-**Example:**
-
-```typescript
-import { useSignalEffect } from "@xmachines/play-react";
-import { useState } from "react";
-
-function RouteDisplay({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
+```tsx
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import type { StateStore } from "@json-render/core";
 
-	useSignalEffect(() => {
-		const currentRoute = actor.currentRoute.get();
-		setRoute(currentRoute);
-	});
+const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "alice" }) });
 
-	return <div>Current Route: {route ?? "None"}</div>;
-}
+<PlayRenderer actor={actor} registry={registry} store={store} actions={{ login: "auth.login" }} />;
 ```
 
-### PlayErrorBoundary
-
-React class component error boundary for catching catalog component render errors.
-
-`PlayRenderer` wraps its render output in `PlayErrorBoundary` automatically. You can also use it directly to wrap any component that may throw during render.
-
-```typescript
-interface PlayErrorBoundaryProps {
-	fallback?: React.ReactNode; // UI shown when a child throws (default: null)
-	children: React.ReactNode;
-	onError?: (error: Error, info: React.ErrorInfo) => void; // Forward to Sentry, Datadog, etc.
-}
-```
+**`fallback`** — Shown when `actor.currentView.get()` is `null` (machine in a no-view state, or during initialisation).
 
-**Props:**
+---
 
-- `fallback` — ReactNode rendered when a child component throws. Defaults to `null`.
-- `onError` — Optional callback forwarded on every caught error. Use for production observability (Sentry, Datadog, custom logging).
+### `useActor`
 
-**Example:**
+Hook for accessing the actor from inside any component rendered by `PlayRenderer`. No prop drilling needed.
 
 ```tsx
-import { PlayErrorBoundary } from "@xmachines/play-react";
+import { useActor } from "@xmachines/play-react";
 
-<PlayErrorBoundary
-	fallback={<div className="error">Something went wrong.</div>}
-	onError={(error) => Sentry.captureException(error)}
->
-	<YourCatalogComponent />
-</PlayErrorBoundary>;
+// Works in any component rendered inside PlayRenderer:
+function LogoutButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "auth.logout" })}>Log Out</button>;
+}
 ```
 
-Works with React 18 and React 19. Uses the standard class component `componentDidCatch` + `getDerivedStateFromError` pattern.
+Throws `"useActor() must be called inside <PlayRenderer>"` if called outside the tree.
 
-## Examples
+---
 
-### Component Receiving Props from Catalog
+### `useSignalEffect`
 
-```typescript
-import { PlayRenderer } from "@xmachines/play-react";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { z } from "zod";
-
-// Define schema in catalog
-const catalog = defineCatalog({
-	UserProfile: z.object({
-		userId: z.string(),
-		name: z.string(),
-		avatar: z.string().url().optional(),
-		stats: z.object({
-			posts: z.number(),
-			followers: z.number(),
-		}),
-	}),
-});
+Hook for subscribing to TC39 Signals in React components that live outside a `PlayRenderer` tree (e.g. nav bars, status indicators driven by actor state).
 
-// Component receives type-safe props + send
-const components = {
-	UserProfile: ({ userId, name, avatar, stats, send }) => (
-		<div>
-			{avatar && <img src={avatar} alt={name} />}
-			<h1>{name}</h1>
-			<p>ID: {userId}</p>
-			<div>
-				<span>{stats.posts} posts</span>
-				<span>{stats.followers} followers</span>
-			</div>
-			<button
-				onClick={() =>
-					send({
-						type: "profile.edit",
-						userId,
-					})
-				}
-			>
-				Edit Profile
-			</button>
-		</div>
-	),
-};
-
-<PlayRenderer actor={actor} components={components} />;
-```
-
-### useSignalEffect for Custom Rendering
-
-```typescript
+```tsx
 import { useSignalEffect } from "@xmachines/play-react";
-import { AbstractActor } from "@xmachines/play-actor";
 
-function CustomRenderer({ actor }: { actor: AbstractActor<any> }) {
-	const [view, setView] = useState(null);
+function NavBar({ actor }: { actor: ReturnType<typeof createPlayer> }) {
+	const [isAuth, setIsAuth] = useState(false);
 
-	// Subscribe to currentView signal
 	useSignalEffect(() => {
-		const currentView = actor.currentView.get();
-		setView(currentView);
+		const snap = actor.state.get();
+		setIsAuth((snap.context as { isAuthenticated: boolean }).isAuthenticated);
 	});
 
-	if (!view) return <div>No view</div>;
-
-	// Custom rendering logic
-	if (view.component === "SpecialCase") {
-		return <SpecialCaseComponent {...view.props} actor={actor} />;
-	}
-
-	// Fallback to standard rendering
-	return <DefaultComponent view={view} actor={actor} />;
+	return <nav>{isAuth ? <LogoutBtn /> : <LoginBtn />}</nav>;
 }
 ```
 
-### Provider Pattern
+---
 
-```typescript
-import { PlayTanStackRouterProvider } from "@xmachines/play-tanstack-react-router";
-import { PlayRenderer } from "@xmachines/play-react";
+### `PlayErrorBoundary`
 
-// Renderer receives actor via props (not children)
-function App() {
-	return (
-		<PlayTanStackRouterProvider
-			actor={actor}
-			router={router}
-			renderer={(currentActor, currentRouter) => {
-				void currentRouter;
-				return (
-				<div>
-					<Header actor={currentActor} />
-					<PlayRenderer actor={currentActor} components={components} />
-					<Footer />
-				</div>
-				);
-			}}
-		/>
-	);
-}
+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.
 
-// Header component also receives actor
-function Header({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
-
-	useSignalEffect(() => {
-		setRoute(actor.currentRoute.get());
-	});
+```tsx
+import { PlayErrorBoundary } from "@xmachines/play-react";
 
-	return (
-		<header>
-			<nav>Current: {route}</nav>
-		</header>
-	);
-}
+<PlayErrorBoundary fallback={<p>Something went wrong.</p>}>
+	<PlayRenderer actor={actor} registry={registry} />
+</PlayErrorBoundary>;
 ```
 
-## Architecture
-
-This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
-
-1. **No Business Logic in React:**
-    - No useState/useReducer for business state
-    - No useEffect for side effects
-    - React only triggers renders, doesn't control state
-
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via `useSignalEffect`
+---
 
-3. **Event Forwarding:**
-    - Components receive `send` function via props
-    - User actions send events to actor (e.g., `{ type: "auth.login" }`)
-    - Actor guards validate and process events
+## Route Parameters in Props
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents React thrashing from multiple signal updates
-    - Single React render per microtask batch
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
 
-5. **Explicit Disposal Contract:**
-    - Component teardown must call watcher `unwatch` in cleanup
-    - Do not rely on GC-only cleanup
-
-**Pattern:**
-
-- Renderer receives actor via props (provider pattern)
-- Enables composition with navigation, headers, footers
-- Supports multiple renderers in same app
-
-**Architectural Invariants:**
-
-- **Signal-Only Reactivity (INV-05):** No React state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+```ts
+// spec: { section: undefined, user: "alice" }
+// After play.route to /settings/profile → context.routeParams = { section: "profile" }
+// Component receives: { section: "profile", user: "alice" }
+```
 
-## Benefits
+Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
 
-- **Framework Swappable:** Business logic has zero React imports
-- **Type Safety:** Props validated against catalog schemas
-- **Simple Testing:** Test actors without React renderer
-- **Performance:** Microtask batching reduces unnecessary renders
-- **Composability:** Renderer prop enables complex layouts ()
+---
 
-## Related Packages
+## Error Handling
 
-- **[@xmachines/play-xstate](../play-xstate)** - XState adapter providing actors
-- **[@xmachines/play-catalog](../play-catalog)** - UI schema validation
-- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router)** - TanStack Router integration
-- **[@xmachines/play-actor](../play-actor)** - Actor base
-- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
+| 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 |
 
-## License
+---
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+## Architecture Notes
 
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+- React `useState` is **only** used to trigger re-renders — never for business logic
+- `actor.currentView` (TC39 Signal) is the sole render trigger; `PlayRenderer` is a passive observer
+- Per-view UI state lives in an `@xstate/store` atom, not in React state
+- `@json-render/react` drives rendering; `PlayRenderer` is the signal bridge — import `defineRegistry`, `ComponentFn`, `ComponentContext`, and `useStateBinding` from `@xmachines/play-react`

package/dist/PlayErrorBoundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayErrorBoundary.d.ts","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,SAAQ,KAAK,CAAC,SAAS,CACrD,sBAAsB,EACtB,sBAAsB,CACtB;gBACY,KAAK,EAAE,sBAAsB;IAKzC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,sBAAsB;IAI5D,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI;IAK5D,MAAM,IAAI,KAAK,CAAC,SAAS;CAMlC"}
+{"version":3,"file":"PlayErrorBoundary.d.ts","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,SAAQ,KAAK,CAAC,SAAS,CACrD,sBAAsB,EACtB,sBAAsB,CACtB;gBACY,KAAK,EAAE,sBAAsB;IAKzC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,sBAAsB;IAI5D,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI;IAO5D,MAAM,IAAI,KAAK,CAAC,SAAS;CAMlC"}

package/dist/PlayErrorBoundary.js

@@ -4,6 +4,7 @@
  * @packageDocumentation
  */
 import React from "react";
+import { RendererError } from "./errors.js";
 /**
  * React class component error boundary for catching catalog component render errors.
  *
@@ -29,8 +30,10 @@ export class PlayErrorBoundary extends React.Component {
         return { hasError: true, error };
     }
     componentDidCatch(error, info) {
-        console.error("[PlayErrorBoundary] Component render error:", error, info);
         this.props.onError?.(error, info);
+        throw new RendererError("Component render error caught by PlayErrorBoundary.", {
+            cause: error,
+        });
     }
     render() {
         if (this.state.hasError) {

package/dist/PlayErrorBoundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayErrorBoundary.js","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AA0B1B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK,CAAC,SAG5C;IACA,YAAY,KAA6B;QACxC,KAAK,CAAC,KAAK,CAAC,CAAC;QACb,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC3C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAEQ,iBAAiB,CAAC,KAAY,EAAE,IAAqB;QAC7D,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAEQ,MAAM;QACd,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC5B,CAAC;CACD"}
+{"version":3,"file":"PlayErrorBoundary.js","sourceRoot":"","sources":["../src/PlayErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA0B5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK,CAAC,SAG5C;IACA,YAAY,KAA6B;QACxC,KAAK,CAAC,KAAK,CAAC,CAAC;QACb,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC3C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAEQ,iBAAiB,CAAC,KAAY,EAAE,IAAqB;QAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,aAAa,CAAC,qDAAqD,EAAE;YAC9E,KAAK,EAAE,KAAK;SACZ,CAAC,CAAC;IACJ,CAAC;IAEQ,MAAM;QACd,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC5B,CAAC;CACD"}

package/dist/PlayRenderer.d.ts

@@ -1,18 +1,24 @@
 /**
  * PlayRenderer - Main React renderer component for XMachines Play architecture
  *
+ * Backed by @json-render/react for spec-driven UI rendering.
+ *
  * @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 (per RESEARCH.md Pattern 1):
+ * Architecture:
  * - Subscribes to actor.currentView signal via useSignalEffect
- * - Dynamically renders catalog components based on view.component string
- * - Forwards user events to actor via actor.send()
- * - React state only for triggering renders, NOT business logic
+ * - Renders view.spec via StateProvider → ActionProvider → VisibilityProvider → Renderer
+ * - Routes action names to actor.send() via the `actions` prop mapping
+ * - 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.
@@ -21,37 +27,22 @@ import type { PlayRendererProps } from "./types.js";
  * @example
  * ```typescript
  * import { PlayRenderer } from "@xmachines/play-react";
- * import { definePlayer } from "@xmachines/play-xstate";
+ * import { defineRegistry } from "@json-render/react";
  *
- * const actor = definePlayer({ machine, catalog })();
- * actor.start();
+ * const { registry } = defineRegistry(catalog, { components: { ... } });
  *
- * const components = {
- *   Dashboard: ({ userId, send }) => <div>User: {userId}</div>,
- *   LoginForm: ({ error, send }) => <form onSubmit={(e) => {
- *     e.preventDefault();
- *     send({ type: "intent", name: "login.submit", payload: {...} });
- *   }}>...</form>
- * };
+ * // Uncontrolled — fresh atom created per view, seeded from spec.state:
+ * <PlayRenderer actor={actor} registry={registry} actions={{ login: "auth.login" }} />
  *
- * <PlayRenderer actor={actor} components={components} />
+ * // 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} registry={registry} store={store} actions={{ login: "auth.login" }} />
  * ```
  *
  * @param props - Component props
  * @returns React element rendering current view from actor
- *
- * @remarks
- * **Component lookup:** Dynamically looks up component from `components` map
- * using `view.component` string from actor.currentView signal.
- *
- * **Event forwarding:** Injects `send` function as prop to components. Components
- * call `send(event)` to forward intents to actor. Actor guards decide validity.
- *
- * **Error handling:** If component not found in catalog, logs error and shows
- * fallback. This indicates missing component registration, not runtime error.
- *
- * **CRITICAL:** Never call actor.send() during render - only in event handlers.
- * Calling send during render causes infinite render loops.
  */
 export declare const PlayRenderer: React.FC<PlayRendererProps>;
 //# 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;;;;GAIG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AAGxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA+CpD,CAAC"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAA2B,MAAM,OAAO,CAAC;AAOhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAYpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAoEpD,CAAC"}

package/dist/PlayRenderer.js

@@ -2,19 +2,36 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 /**
  * PlayRenderer - Main React renderer component for XMachines Play architecture
  *
+ * Backed by @json-render/react for spec-driven UI rendering.
+ *
  * @packageDocumentation
  */
-import React, { useState } from "react";
+import React, { useState, useRef } from "react";
+import { Renderer, StateProvider, ActionProvider, VisibilityProvider } 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) });
+}
 /**
  * Main renderer component that subscribes to actor signals and renders UI
+ * via @json-render/react Renderer.
  *
- * Architecture (per RESEARCH.md Pattern 1):
+ * Architecture:
  * - Subscribes to actor.currentView signal via useSignalEffect
- * - Dynamically renders catalog components based on view.component string
- * - Forwards user events to actor via actor.send()
- * - React state only for triggering renders, NOT business logic
+ * - Renders view.spec via StateProvider → ActionProvider → VisibilityProvider → Renderer
+ * - Routes action names to actor.send() via the `actions` prop mapping
+ * - 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.
@@ -23,66 +40,64 @@ import { PlayErrorBoundary } from "./PlayErrorBoundary.js";
  * @example
  * ```typescript
  * import { PlayRenderer } from "@xmachines/play-react";
- * import { definePlayer } from "@xmachines/play-xstate";
+ * import { defineRegistry } from "@json-render/react";
  *
- * const actor = definePlayer({ machine, catalog })();
- * actor.start();
+ * const { registry } = defineRegistry(catalog, { components: { ... } });
  *
- * const components = {
- *   Dashboard: ({ userId, send }) => <div>User: {userId}</div>,
- *   LoginForm: ({ error, send }) => <form onSubmit={(e) => {
- *     e.preventDefault();
- *     send({ type: "intent", name: "login.submit", payload: {...} });
- *   }}>...</form>
- * };
+ * // Uncontrolled — fresh atom created per view, seeded from spec.state:
+ * <PlayRenderer actor={actor} registry={registry} actions={{ login: "auth.login" }} />
  *
- * <PlayRenderer actor={actor} components={components} />
+ * // 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} registry={registry} store={store} actions={{ login: "auth.login" }} />
  * ```
  *
  * @param props - Component props
  * @returns React element rendering current view from actor
- *
- * @remarks
- * **Component lookup:** Dynamically looks up component from `components` map
- * using `view.component` string from actor.currentView signal.
- *
- * **Event forwarding:** Injects `send` function as prop to components. Components
- * call `send(event)` to forward intents to actor. Actor guards decide validity.
- *
- * **Error handling:** If component not found in catalog, logs error and shows
- * fallback. This indicates missing component registration, not runtime error.
- *
- * **CRITICAL:** Never call actor.send() during render - only in event handlers.
- * Calling send during render causes infinite render loops.
  */
-export const PlayRenderer = ({ actor, components, fallback = null, }) => {
+export const PlayRenderer = ({ actor, registry, store: externalStore, fallback = null, actions = {}, }) => {
     // 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
+    // No view in current state — render fallback
     if (!view) {
         return _jsx(_Fragment, { children: fallback });
     }
-    // Handle null/undefined components catalog gracefully
-    if (!components) {
-        console.error(`Components catalog is ${components === null ? "null" : "undefined"}. ` +
-            `Cannot render component "${view.component}".`);
-        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;
     }
-    // Look up component from catalog
-    const Component = components[view.component];
-    if (!Component) {
-        console.error(`Component "${view.component}" not found in catalog. ` +
-            `Available components: ${Object.keys(components).join(", ")}`);
-        return _jsx(_Fragment, { children: fallback });
+    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;
     }
-    // Render with props from actor + send function
-    // bind(actor) ensures 'this' context is correct when components call send()
-    return (_jsx(PlayErrorBoundary, { fallback: fallback, children: _jsx(Component, { ...view.props, send: actor.send.bind(actor) }) }));
+    // Build ActionProvider handlers from actions mapping
+    // Each handler calls actor.send() with the configured event type + params
+    const handlers = Object.fromEntries(Object.entries(actions).map(([actionName, eventType]) => [
+        actionName,
+        async (params = {}) => actor.send({ type: eventType, ...params }),
+    ]));
+    return (_jsx(ActorContext.Provider, { value: actor, children: _jsx(PlayErrorBoundary, { fallback: fallback, children: _jsx(StateProvider, { store: store, children: _jsx(ActionProvider, { handlers: handlers, children: _jsx(VisibilityProvider, { children: _jsx(Renderer, { spec: view.spec ?? null, registry: registry }) }) }) }) }) }));
 };
 //# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":";AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgC,CAAC,EACzD,KAAK,EACL,UAAU,EACV,QAAQ,GAAG,IAAI,GACf,EAAE,EAAE;IACJ,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAsB,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAErF,8BAA8B;IAC9B,eAAe,CAAC,GAAG,EAAE;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QAC5C,OAAO,CAAC,WAAW,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,2BAA2B;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,sDAAsD;IACtD,IAAI,CAAC,UAAU,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,CACZ,yBAAyB,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI;YACtE,4BAA4B,IAAI,CAAC,SAAS,IAAI,CAC/C,CAAC;QACF,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,iCAAiC;IACjC,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE7C,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACZ,cAAc,IAAI,CAAC,SAAS,0BAA0B;YACrD,yBAAyB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9D,CAAC;QACF,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,+CAA+C;IAC/C,4EAA4E;IAC5E,OAAO,CACN,KAAC,iBAAiB,IAAC,QAAQ,EAAE,QAAQ,YACpC,KAAC,SAAS,OAAK,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAI,GACxC,CACpB,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":";AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjG,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAkB,MAAM,eAAe,CAAC;AAE7D;;;GAGG;AACH,SAAS,eAAe,CAAC,YAAqC;IAC7D,OAAO,qBAAqB,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgC,CAAC,EACzD,KAAK,EACL,QAAQ,EACR,KAAK,EAAE,aAAa,EACpB,QAAQ,GAAG,IAAI,EACf,OAAO,GAAG,EAAE,GACZ,EAAE,EAAE;IACJ,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAsB,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAErF,+DAA+D;IAC/D,qFAAqF;IACrF,0CAA0C;IAC1C,MAAM,gBAAgB,GAAG,MAAM,CAAoB,IAAI,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,MAAM,CAAsB,IAAI,CAAC,CAAC;IAEtD,8BAA8B;IAC9B,eAAe,CAAC,GAAG,EAAE;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QAC5C,OAAO,CAAC,WAAW,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,6CAA6C;IAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,8CAA8C;IAC9C,+DAA+D;IAC/D,0EAA0E;IAC1E,IAAI,KAAiB,CAAC;IACtB,IAAI,aAAa,EAAE,CAAC;QACnB,KAAK,GAAG,aAAa,CAAC;IACvB,CAAC;SAAM,CAAC;QACP,6DAA6D;QAC7D,mEAAmE;QACnE,IAAI,gBAAgB,CAAC,OAAO,KAAK,IAAI,IAAI,WAAW,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACvE,MAAM,YAAY,GAAI,IAAI,CAAC,IAAI,EAAE,KAAiC,IAAI,EAAE,CAAC;YACzE,gBAAgB,CAAC,OAAO,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;YACzD,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;QAC5B,CAAC;QACD,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC;IAClC,CAAC;IAED,qDAAqD;IACrD,0EAA0E;IAC1E,MAAM,QAAQ,GAAkC,MAAM,CAAC,WAAW,CACjE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC;QACxD,UAAU;QACV,KAAK,EAAE,SAAkC,EAAE,EAAE,EAAE,CAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAAC;KAC3C,CAAC,CACF,CAAC;IAEF,OAAO,CACN,KAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAkB,YAC/C,KAAC,iBAAiB,IAAC,QAAQ,EAAE,QAAQ,YACpC,KAAC,aAAa,IAAC,KAAK,EAAE,KAAK,YAC1B,KAAC,cAAc,IAAC,QAAQ,EAAE,QAAQ,YACjC,KAAC,kBAAkB,cAClB,KAAC,QAAQ,IAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,QAAQ,EAAE,QAAQ,GAAI,GACrC,GACL,GACF,GACG,GACG,CACxB,CAAC;AACH,CAAC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Thrown by `PlayErrorBoundary.componentDidCatch()` when a React component inside
+ * the boundary throws during rendering.
+ *
+ * The original render error is set as `cause`. The `onError` prop callback fires
+ * before this error is thrown, allowing observability tools to record the incident.
+ *
+ * **Error code:** `PLAY_RENDERER_RENDER_ERROR`
+ *
+ * @example
+ * ```typescript
+ * import { RendererError } from "@xmachines/play-react/errors";
+ *
+ * // In a parent error boundary or global handler:
+ * if (err instanceof RendererError) {
+ *   // err.cause is the original component error
+ *   reportRenderError(err.cause as Error);
+ * }
+ * ```
+ */
+export declare class RendererError extends PlayError {
+    constructor(message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD"}

package/dist/errors.js

@@ -0,0 +1,28 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Thrown by `PlayErrorBoundary.componentDidCatch()` when a React component inside
+ * the boundary throws during rendering.
+ *
+ * The original render error is set as `cause`. The `onError` prop callback fires
+ * before this error is thrown, allowing observability tools to record the incident.
+ *
+ * **Error code:** `PLAY_RENDERER_RENDER_ERROR`
+ *
+ * @example
+ * ```typescript
+ * import { RendererError } from "@xmachines/play-react/errors";
+ *
+ * // In a parent error boundary or global handler:
+ * if (err instanceof RendererError) {
+ *   // err.cause is the original component error
+ *   reportRenderError(err.cause as Error);
+ * }
+ * ```
+ */
+export class RendererError extends PlayError {
+    constructor(message, options) {
+        super("PlayRenderer", "PLAY_RENDERER_RENDER_ERROR", message, options);
+        this.name = "RendererError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC3C,YAAY,OAAe,EAAE,OAAsB;QAClD,KAAK,CAAC,cAAc,EAAE,4BAA4B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC7B,CAAC;CACD"}

package/dist/index.d.ts

@@ -2,19 +2,27 @@
  * @xmachines/play-react - React renderer for XMachines Play architecture
  *
  * Provides a thin React rendering layer that passively observes actor signals
- * and renders UI components from catalog definitions. This package enables
+ * 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.
  *
  * **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`, `useStateBinding`, `ComponentFn`, and
+ * `ComponentContext` from `@json-render/react` so consumers import everything
+ * from `@xmachines/play-react` rather than `@json-render/react` directly.
+ *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
 export { PlayRenderer } from "./PlayRenderer.js";
 export { useSignalEffect } from "./useSignalEffect.js";
 export { PlayErrorBoundary } from "./PlayErrorBoundary.js";
+export { useActor } from "./useActor.js";
+export { defineRegistry, useStateBinding } from "@json-render/react";
+export type { ComponentFn, ComponentContext } from "@json-render/react";
 export type { PlayRendererProps } from "./types.js";
 export type { PlayErrorBoundaryProps, PlayErrorBoundaryState } from "./PlayErrorBoundary.js";
+export type { PlayActor } from "./useActor.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;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}
+{"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,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC7F,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -2,13 +2,17 @@
  * @xmachines/play-react - React renderer for XMachines Play architecture
  *
  * Provides a thin React rendering layer that passively observes actor signals
- * and renders UI components from catalog definitions. This package enables
+ * 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.
  *
  * **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`, `useStateBinding`, `ComponentFn`, and
+ * `ComponentContext` from `@json-render/react` so consumers import everything
+ * from `@xmachines/play-react` rather than `@json-render/react` directly.
+ *
  * @packageDocumentation
  * @module @xmachines/play-react
  */
@@ -16,4 +20,8 @@
 export { PlayRenderer } from "./PlayRenderer.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, useStateBinding } 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;;;;;;;;;;;;;GAaG;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"}
+{"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,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types.d.ts

@@ -3,22 +3,52 @@
  *
  * @packageDocumentation
  */
+import type { ComponentRegistry } 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";
+import type { AnyActorLogic, EventFromLogic } from "xstate";
 /**
  * Props for PlayRenderer component
  *
+ * @typeParam TLogic - The XState actor logic type. Defaults to `AnyActorLogic` for
+ *   non-generic usage. When a specific machine type is provided, the `actions` values
+ *   are constrained to the event type strings that the machine actually accepts.
+ *
  * @property actor - Actor instance with currentView signal (requires Viewable capability)
- * @property components - Map of component names to React components
+ * @property registry - ComponentRegistry from defineRegistry() in @json-render/react
+ * @property store - Optional external StateStore (e.g. from @json-render/xstate). When
+ *   provided, PlayRenderer operates in controlled mode — spec.state is ignored and the
+ *   store is the single source of truth for UI state. When omitted, a fresh
+ *   @xstate/store atom is created internally per view transition, seeded from spec.state.
  * @property fallback - Optional component shown when currentView is null
+ * @property actions - Maps json-render action names to XState event type strings.
+ *   Values are constrained to `EventFromLogic<TLogic>["type"]` — passing a non-existent
+ *   event type string is a compile error when TLogic is specified.
  */
-export interface PlayRendererProps {
+export interface PlayRendererProps<TLogic extends AnyActorLogic = AnyActorLogic> {
     /** Actor instance with currentView signal (requires Viewable capability) */
-    actor: AbstractActor<AnyActorLogic> & Viewable;
-    /** Map of component names to React components */
-    components: Record<string, React.ElementType>;
+    actor: AbstractActor<TLogic> & Viewable;
+    /** ComponentRegistry from defineRegistry() in @json-render/react */
+    registry: ComponentRegistry;
+    /**
+     * 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. The atom resets automatically when the actor transitions to a
+     * new view, mirroring the actor's currentView lifecycle.
+     */
+    store?: StateStore;
     /** Optional component shown when currentView is null */
     fallback?: React.ReactNode;
+    /**
+     * Maps json-render action names to XState event type strings.
+     * Values are constrained to valid event types for TLogic — wrong event type strings
+     * are caught at compile time when TLogic is specified.
+     */
+    actions?: {
+        [actionName: string]: EventFromLogic<TLogic>["type"];
+    };
 }
 //# 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,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;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAE/C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAE9C,wDAAwD;IACxD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,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,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa;IAC9E,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;IAExC,oEAAoE;IACpE,QAAQ,EAAE,iBAAiB,CAAC;IAE5B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE3B;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACnE"}

package/dist/useActor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * useActor — React hook for accessing the raw actor inside a PlayRenderer tree.
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { useActor } from "@xmachines/play-react";
+ *
+ * function MyComponent() {
+ *   const actor = useActor();
+ *   return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { AbstractActor } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+export type PlayActor = AbstractActor<AnyActorLogic>;
+export declare const ActorContext: import("react").Context<PlayActor | null>;
+export declare function useActor(): PlayActor;
+//# sourceMappingURL=useActor.d.ts.map

package/dist/useActor.d.ts.map

@@ -0,0 +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"}

package/dist/useActor.js

@@ -0,0 +1,29 @@
+/**
+ * useActor — React hook for accessing the raw actor inside a PlayRenderer tree.
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { useActor } from "@xmachines/play-react";
+ *
+ * function MyComponent() {
+ *   const actor = useActor();
+ *   return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { createContext, useContext } from "react";
+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;
+}
+//# sourceMappingURL=useActor.js.map

package/dist/useActor.js.map

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-react",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.17",
   "description": "React renderer for XMachines Play architecture with signal-driven rendering",
   "keywords": [
     "actor",
@@ -37,6 +37,7 @@
     "build": "tsc --build",
     "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
     "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "typecheck:browser": "tsc --noEmit -p tsconfig.browser.json",
     "test": "vitest",
     "test:vitest": "vitest run",
@@ -44,23 +45,31 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play-actor": "1.0.0-beta.15",
-    "@xmachines/play-catalog": "1.0.0-beta.15",
-    "@xmachines/play-signals": "1.0.0-beta.15"
+    "@xmachines/play-actor": "1.0.0-beta.17",
+    "@xmachines/play-signals": "1.0.0-beta.17"
   },
   "devDependencies": {
+    "@json-render/core": "^0.16.0",
+    "@json-render/react": "^0.16.0",
+    "@json-render/xstate": "^0.16.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@xmachines/shared": "1.0.0-beta.15",
+    "@xmachines/shared": "1.0.0-beta.17",
+    "@xstate/store": ">=3.17.0",
     "jsdom": "^29.0.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3 || ^6.0.2",
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
+    "@json-render/core": "^0.16.0",
+    "@json-render/react": "^0.16.0",
+    "@json-render/xstate": "^0.16.0",
+    "@xstate/store": ">=3.17.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }