@xmachines/play-react 1.0.0-beta.4 → 1.0.0-beta.41

package/README.md

@@ -1,358 +1,398 @@
 # @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 [Play RFC](../docs/rfc/play.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`
-- `PlayRendererProps` (type)
+In this monorepo, the root install applies a `patch-package` patch to `@json-render/react`
+so `defineRegistry(..., { onRenderError })` can intercept inner element-boundary errors
+without muting console output.
 
-**Peer dependencies:**
+## Current Exports
 
-- `react` ^18.0.0 - React runtime
-- `react-dom` ^18.0.0 - React DOM renderer
+- `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`
+- `useBoundProp` — re-exported from `@json-render/react`
+- `ComponentFn` (type) — re-exported from `@json-render/react`
+- `ComponentContext` (type) — re-exported from `@json-render/react`
+- `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
 
-```typescript
-import { createRoot } from "react-dom/client";
-import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { PlayRenderer } from "@xmachines/play-react";
+```tsx
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+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";
+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. 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 action handlers
+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" });
+		},
+	},
 });
 
-// 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"),
-					password: data.get("password"),
-				});
-			}}
-		>
-			{error && <p style={{ color: "red" }}>{error}</p>}
-			<input name="username" required placeholder="Username" />
-			<input name="password" type="password" required placeholder="Password" />
-			<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 });
+// 4. Define machine with view metadata
+const machine = setup({
+	types: {
+		context: {} as {
+			isAuthenticated: boolean;
+			username: string | null;
+			params: Record<string, string>;
+			query: 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, params: {}, query: {} },
+		states: {
+			login: {
+				id: "login",
+				meta: {
+					route: "/login",
+					view: {
+						root: "root",
+						elements: {
+							root: { type: "Login", props: { title: "Sign In" }, children: [] },
+						},
+					},
+				},
+			},
+			dashboard: {
+				id: "dashboard",
+				meta: {
+					route: "/dashboard",
+					view: {
+						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 (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
+}
 ```
 
 ## API Reference
 
-### PlayRenderer
-
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
-
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<any>;
-	components: Record<string, React.ComponentType<any>>;
-	fallback?: React.ReactNode;
-}
+### `PlayUIProvider`
+
+Batteries-included composite provider. Wraps `ActorProvider` + `JSONUIProvider`. Pass `actor` and `registryResult` here, then place `<PlayRenderer />` inside as a zero-prop child.
+
+```tsx
+<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>
 ```
 
-**Props:**
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to React components
-- `fallback` - Component shown when `currentView` is null (default: `null`)
+**`registryResult`** — Full result from `defineRegistry(catalog, { components, actions })`. Contains both the component registry and action handlers.
 
-**Behavior:**
+**`store`** (optional) — Controls per-view UI state (form values, `$state` bindings):
 
-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
+- **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:**
+```tsx
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import type { StateStore } from "@json-render/core";
 
-```typescript
-<PlayRenderer
-	actor={actor}
-	components={{
-		HomePage: ({ send }) => <div>Home</div>,
-		AboutPage: ({ send }) => <div>About</div>,
-	}}
-	fallback={<div>Loading...</div>}
-/>
+const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "alice" }) });
+
+<PlayUIProvider actor={actor} registryResult={registryResult} store={store}>
+	<PlayRenderer />
+</PlayUIProvider>;
 ```
 
-### useSignalEffect()
+**`fallback`** — Shown when `actor.currentView.get()` is `null` (machine in a no-view state, or during initialisation).
 
-Hook for subscribing to signal changes with automatic cleanup:
+**`onError`** — Called when the outer `PlayErrorBoundary` catches an error. Receives `(error: Error, info: React.ErrorInfo)`. Use for observability tools (Sentry, Datadog, etc.).
 
-```typescript
-useSignalEffect(() => {
-	const value = signal.get();
-	// React re-renders when signal changes
-});
+**`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>;
 ```
 
-**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`
+### `PlayRenderer`
 
-**Canonical watcher lifecycle:**
+Zero-prop leaf component. Must be rendered inside a `PlayUIProvider` (or `ActorProvider`) tree. Subscribes to `actor.currentView` via context and renders the current spec.
 
-1. `notify`
-2. `queueMicrotask`
-3. drain pending work (`getPending` and/or `Computed.get`)
-4. run effect + trigger render
-5. re-arm watcher via `watch()`
+```tsx
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
+```
 
-Watcher notification is one-shot, so re-arm and explicit cleanup are both required.
+`PlayRenderer` accepts no props — all configuration (`actor`, `registryResult`, `store`, `fallback`, `onError`, `onRenderError`) is provided by the enclosing `PlayUIProvider` or `ActorProvider`.
 
-**Example:**
+## Error handling
 
-```typescript
-import { useSignalEffect } from "@xmachines/play-react";
-import { useState } from "react";
+The provider tree has two layers of error boundaries:
 
-function RouteDisplay({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
+### Outer boundary — `onError` and `fallback`
 
-	useSignalEffect(() => {
-		const currentRoute = actor.currentRoute.get();
-		setRoute(currentRoute);
-	});
+Wraps the entire renderer output via `PlayErrorBoundary`. Triggered when the spec or store setup throws, or when the inner boundary is not present.
 
-	return <div>Current Route: {route ?? "None"}</div>;
-}
+```tsx
+<PlayUIProvider
+	actor={actor}
+	registryResult={registryResult}
+	fallback={<p>Something went wrong.</p>}
+	onError={(err, info) => Sentry.captureException(err, { extra: info })}
+>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
-**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-react)
+### Inner boundary — `onRenderError`
 
-## Examples
+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.
 
-### Component Receiving Props from Catalog
+Pass `onRenderError` to `PlayUIProvider` (or `ActorProvider`) — overrides any registry-level handler — or bake it into `defineRegistry`:
 
-```typescript
-import { PlayRenderer } from "@xmachines/play-react";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { z } from "zod";
+```tsx
+// via PlayUIProvider prop
+<PlayUIProvider
+	actor={actor}
+	registryResult={registryResult}
+	onRenderError={(error, elementType) => {
+		console.warn(`<${elementType}> crashed:`, error);
+	}}
+>
+	<PlayRenderer />
+</PlayUIProvider>
+```
 
-// 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(),
-		}),
-	}),
+```ts
+// via defineRegistry — bakes the handler into the registry
+const registryResult = defineRegistry(catalog, {
+	components: { Login, Dashboard },
+	actions: { login: async (params) => { ... }, logout: async () => { ... } },
+	onRenderError(error, elementType) {
+		reportExpectedRenderError(error, elementType);
+	},
 });
-
-// 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
+`onRenderError` is typed as `RenderErrorHandler` and exported from `@xmachines/play-react`.
 
-```typescript
-import { useSignalEffect } from "@xmachines/play-react";
-import { AbstractActor } from "@xmachines/play-actor";
+---
 
-function CustomRenderer({ actor }: { actor: AbstractActor<any> }) {
-	const [view, setView] = useState(null);
+### `useActor`
 
-	// Subscribe to currentView signal
-	useSignalEffect(() => {
-		const currentView = actor.currentView.get();
-		setView(currentView);
-	});
-
-	if (!view) return <div>No view</div>;
+Hook for accessing the actor from inside any component rendered by `PlayRenderer`. No prop drilling needed.
 
-	// Custom rendering logic
-	if (view.component === "SpecialCase") {
-		return <SpecialCaseComponent {...view.props} actor={actor} />;
-	}
+```tsx
+import { useActor } from "@xmachines/play-react";
 
-	// Fallback to standard rendering
-	return <DefaultComponent view={view} actor={actor} />;
+// Works in any component rendered inside PlayRenderer:
+function LogoutButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "auth.logout" })}>Log Out</button>;
 }
 ```
 
-### Provider Pattern
+Throws `NonNullableError: "useActor() must be called inside <ActorProvider> (or <PlayUIProvider>)"` if called outside the tree.
 
-```typescript
-import { PlayTanStackRouterProvider } from "@xmachines/play-tanstack-react-router";
-import { PlayRenderer } from "@xmachines/play-react";
+---
 
-// 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>
-				);
-			}}
-		/>
-	);
-}
+### `useSignalEffect`
 
-// Header component also receives actor
-function Header({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
+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).
+
+```tsx
+import { useSignalEffect } from "@xmachines/play-react";
+
+function NavBar({ actor }: { actor: ReturnType<typeof createPlayer> }) {
+	const [isAuth, setIsAuth] = useState(false);
 
 	useSignalEffect(() => {
-		setRoute(actor.currentRoute.get());
+		const snap = actor.state.get();
+		setIsAuth((snap.context as { isAuthenticated: boolean }).isAuthenticated);
 	});
 
-	return (
-		<header>
-			<nav>Current: {route}</nav>
-		</header>
-	);
+	return <nav>{isAuth ? <LogoutBtn /> : <LoginBtn />}</nav>;
 }
 ```
 
-## Architecture
+---
 
-This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+### `PlayErrorBoundary`
 
-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
+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.
 
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via `useSignalEffect`
+`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.
 
-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
+```tsx
+import { PlayErrorBoundary } from "@xmachines/play-react";
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents React thrashing from multiple signal updates
-    - Single React render per microtask batch
+<PlayErrorBoundary
+	fallback={<p>Something went wrong.</p>}
+	onError={(err, info) => Sentry.captureException(err, { extra: info })}
+>
+	<PlayUIProvider actor={actor} registryResult={registryResult}>
+		<PlayRenderer />
+	</PlayUIProvider>
+</PlayErrorBoundary>;
+```
 
-5. **Explicit Disposal Contract:**
-    - Component teardown must call watcher `unwatch` in cleanup
-    - Do not rely on GC-only cleanup
+---
 
-**Pattern:**
+## Route Parameters in Props
 
-- Renderer receives actor via props (provider pattern)
-- Enables composition with navigation, headers, footers
-- Supports multiple renderers in same app
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
 
-**Architectural Invariants:**
+```ts
+// spec: { section: undefined, user: "alice" }
+// After play.route to /settings/profile → context.params = { section: "profile" }
+// Component receives: { section: "profile", user: "alice" }
+```
 
-- **Signal-Only Reactivity (INV-05):** No React state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
 
-## Benefits
+---
 
-- **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 ()
+## Error Handling
 
-## Related Packages
+| 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 |
 
-- **[@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
+---
 
-## License
+## Architecture Notes
 
-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 `useBoundProp` from `@xmachines/play-react`