@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -1,423 +1,275 @@
-[Documentation](../../README.md) / @xmachines/play-react
+[API](../../README.md) / @xmachines/play-react
 
 # @xmachines/play-react
 
-**React renderer consuming signals and UI schema with provider pattern**
+React renderer for XMachines Play architecture with signal-driven rendering.
 
-Signal-driven React rendering layer observing actor state with zero React state for business logic.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-react)
 
-## Overview
+Part of the [xmachines-js monorepo](../../README.md).
 
-`@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.
-
-Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
-
-- **Signal-Only Reactivity (INV-05):** No useState/useReducer for business logic, signals only
-- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
-
-**Key Principle:** React state is never used for business logic. Signals are the source of truth.
+## Installation
 
-Renderer receives actor via props (provider pattern), not children.
+```bash
+pnpm add @xmachines/play-react
+```
 
-## Installation
+**Peer dependencies** (must be installed separately):
 
 ```bash
-npm install react@^18.0.0 react-dom@^18.0.0
-npm install @xmachines/play-react
+pnpm add react react-dom xstate @xstate/store @xmachines/json-render-react @xmachines/json-render-core @xmachines/json-render-xstate
 ```
 
-## Current Exports
+Supported versions:
 
-- `PlayRenderer`
-- `useSignalEffect`
-- `PlayErrorBoundary`
-- `PlayRendererProps` (type)
-- `PlayErrorBoundaryProps` (type)
+- `react` / `react-dom`: `^18.0.0 || ^19.0.0`
+- `xstate`: `^5.31.0`
+- `@xstate/store`: `^3.17.0`
+- `@xmachines/json-render-*`: `^0.18.0`
 
-**Peer dependencies:**
+## Usage
 
-- `react` ^18.0.0 || ^19.0.0 — React runtime
-- `react-dom` ^18.0.0 || ^19.0.0 — React DOM renderer
+### Standard usage — `PlayUIProvider` + `PlayRenderer`
 
-## Quick Start
+The recommended pattern for actor-driven React rendering:
 
-```typescript
-import { createRoot } from "react-dom/client";
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { definePlayer } from "@xmachines/play-xstate";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { PlayRenderer } from "@xmachines/play-react";
-import { z } from "zod";
-
-// 1. Define catalog (business logic layer)
-const catalog = defineCatalog({
-	LoginForm: z.object({ error: z.string().optional() }),
-	Dashboard: z.object({
-		userId: z.string(),
-		username: z.string(),
-	}),
-});
 
-// 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 });
-const actor = createPlayer();
+// 1. Create and start the actor
+const actor = definePlayer({ machine: myMachine })();
 actor.start();
 
-// 4. Render UI (actor via props)
-const root = createRoot(document.getElementById("app")!);
-root.render(<PlayRenderer actor={actor} components={components} />);
-```
-
-## API Reference
-
-### PlayRenderer
-
-Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+// 2. Define the component registry with action handlers
+const registryResult = defineRegistry(myCatalog, {
+	components: { Login, Dashboard },
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
 
-```typescript
-interface PlayRendererProps {
-	actor: AbstractActor<AnyActorLogic> & Viewable;
-	components: Record<string, React.ElementType>;
-	fallback?: React.ReactNode;
+// 3. Render — signals drive view transitions automatically
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 
-**Props:**
-
-- `actor` - Actor instance with `currentView` signal
-- `components` - Map of component names to React components
-- `fallback` - Component shown when `currentView` is null (default: `null`)
+### With optional `JSONUIProvider` props
 
-**Behavior:**
+Pass navigation and validation helpers through `PlayUIProvider`:
 
-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
-
-**Example:**
-
-```typescript
-<PlayRenderer
+```tsx
+<PlayUIProvider
 	actor={actor}
-	components={{
-		HomePage: ({ send }) => <div>Home</div>,
-		AboutPage: ({ send }) => <div>About</div>,
-	}}
-	fallback={<div>Loading...</div>}
-/>
-```
-
-### useSignalEffect()
-
-Hook for subscribing to signal changes with automatic cleanup:
-
-```typescript
-useSignalEffect(() => {
-	const value = signal.get();
-	// React re-renders when signal changes
-});
+	registryResult={registryResult}
+	navigate={(path) => router.push(path)}
+	validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
+>
+	<PlayRenderer />
+</PlayUIProvider>
 ```
 
-**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()`
+### Escape hatch — custom provider composition
 
-Watcher notification is one-shot, so re-arm and explicit cleanup are both required.
+Use `ActorProvider` directly when you need to compose providers manually:
 
-**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);
-
-	useSignalEffect(() => {
-		const currentRoute = actor.currentRoute.get();
-		setRoute(currentRoute);
-	});
+```tsx
+import { ActorProvider, JSONUIProvider, PlayRenderer } from "@xmachines/play-react";
 
-	return <div>Current Route: {route ?? "None"}</div>;
-}
+<ActorProvider actor={actor} registryResult={registryResult}>
+	<JSONUIProvider registry={registryResult.registry}>
+		<PlayRenderer />
+	</JSONUIProvider>
+</ActorProvider>;
 ```
 
-### PlayErrorBoundary
-
-React class component error boundary for catching catalog component render errors.
+### Accessing the actor from inside the tree
 
-`PlayRenderer` wraps its render output in `PlayErrorBoundary` automatically. You can also use it directly to wrap any component that may throw during render.
+```tsx
+import { useActor } from "@xmachines/play-react";
 
-```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.
+function SubmitButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
 }
 ```
 
-**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).
-
-**Example:**
+### Subscribing to signals directly
 
 ```tsx
-import { PlayErrorBoundary } from "@xmachines/play-react";
-
-<PlayErrorBoundary
-	fallback={<div className="error">Something went wrong.</div>}
-	onError={(error) => Sentry.captureException(error)}
->
-	<YourCatalogComponent />
-</PlayErrorBoundary>;
-```
-
-Works with React 18 and React 19. Uses the standard class component `componentDidCatch` + `getDerivedStateFromError` pattern.
-
-## Examples
-
-### Component Receiving Props from Catalog
-
-```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(),
-		}),
-	}),
-});
-
-// 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
 import { useSignalEffect } from "@xmachines/play-react";
-import { AbstractActor } from "@xmachines/play-actor";
 
-function CustomRenderer({ actor }: { actor: AbstractActor<any> }) {
+function MyComponent({ actor }) {
 	const [view, setView] = useState(null);
 
-	// Subscribe to currentView signal
 	useSignalEffect(() => {
-		const currentView = actor.currentView.get();
-		setView(currentView);
-	});
-
-	if (!view) return <div>No view</div>;
-
-	// Custom rendering logic
-	if (view.component === "SpecialCase") {
-		return <SpecialCaseComponent {...view.props} actor={actor} />;
-	}
+		setView(actor.currentView.get());
+	}, [actor]); // deps: re-subscribe when the actor prop swaps
 
-	// Fallback to standard rendering
-	return <DefaultComponent view={view} actor={actor} />;
+	return <div>{view?.component}</div>;
 }
 ```
 
-### Provider Pattern
-
-```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>
-				);
-			}}
-		/>
-	);
-}
-
-// Header component also receives actor
-function Header({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
-
-	useSignalEffect(() => {
-		setRoute(actor.currentRoute.get());
-	});
-
-	return (
-		<header>
-			<nav>Current: {route}</nav>
-		</header>
-	);
-}
+## API Summary
+
+### Components
+
+| Export                | Description                                                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `<PlayUIProvider>`    | Batteries-included provider: wraps `ActorProvider` + `JSONUIProvider`. Standard entry point.                                            |
+| `<PlayRenderer>`      | Zero-prop leaf component. Reads the current actor view from context and renders it. Must be inside `PlayUIProvider` or `ActorProvider`. |
+| `<ActorProvider>`     | Escape-hatch primitive. Owns actor bridging, signal subscription, and per-view `StateStore` lifecycle.                                  |
+| `<PlayErrorBoundary>` | React class error boundary for catching catalog component render errors.                                                                |
+
+### Hooks
+
+| Export                             | Description                                                                                                                                                                                                                          |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useSignalEffect(callback, deps?)` | Subscribes to TC39 signal changes; re-runs the callback when any accessed signal changes (re-render via the callback's own setState). Optional `deps` recreates the subscription, like `useEffect`. Cleanup is automatic on unmount. |
+| `useActor()`                       | Returns the raw actor instance. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                                                      |
+| `usePlayView()`                    | Returns `{ spec, handlers, registry, store }` for the current view. Must be called inside an `ActorProvider`/`PlayUIProvider` tree.                                                                                                  |
+
+### Types
+
+| Export                   | Description                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `PlayUIProviderProps`    | Props for `<PlayUIProvider>`                                                                   |
+| `ActorProviderProps`     | Props for `<ActorProvider>` (also exported as `PlayRendererProps` for migration compatibility) |
+| `PlayErrorBoundaryProps` | Props for `<PlayErrorBoundary>`                                                                |
+| `PlayErrorBoundaryState` | State shape for `<PlayErrorBoundary>`                                                          |
+| `AnyPlayActor`           | Type alias for `AbstractActor<AnyActorLogic>` — the bare actor type used by context providers  |
+| `ViewContextValue`       | Value shape returned by `usePlayView()`                                                        |
+| `RenderErrorHandler`     | Error handler callback type for render errors                                                  |
+
+### Re-exports from `@xmachines/json-render-react`
+
+`@xmachines/play-react` re-exports the full `@xmachines/json-render-react` surface so consumers only need one import:
+
+```ts
+import {
+	defineRegistry,
+	useBoundProp,
+	JSONUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	Renderer,
+} from "@xmachines/play-react";
 ```
 
-## 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
+## Key Principle
 
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via `useSignalEffect`
+React state is **never** used for business logic — only for triggering React's render cycle. Signals (`@xmachines/play-signals`) are the source of truth. `PlayUIProvider` passively observes actor signals via `useSignalEffect` and re-renders when the current view changes. Rapid signal updates are batched via microtasks to prevent unnecessary React renders.
 
-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
+## Testing
 
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents React thrashing from multiple signal updates
-    - Single React render per microtask batch
+Run unit tests (jsdom environment):
 
-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:**
+```bash
+pnpm --filter @xmachines/play-react test
+```
 
-- **Signal-Only Reactivity (INV-05):** No React state for business logic
-- **Passive Infrastructure (INV-04):** Components reflect, never decide
+Run tests with coverage:
 
-## Benefits
+```bash
+pnpm --filter @xmachines/play-react run test:coverage
+```
 
-- **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 ()
+Run browser integration tests (requires Chromium):
 
-## Related Packages
+```bash
+pnpm --filter @xmachines/play-react run test:browser
+```
 
-- **[@xmachines/play-xstate](../play-xstate/README.md)** - XState adapter providing actors
-- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
-- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** - TanStack Router integration
-- **[@xmachines/play-actor](../play-actor/README.md)** - Actor base
-- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
+Coverage thresholds: 80% lines, functions, branches, and statements.
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](./LICENSE).
 
 @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
+Provides a provider-based React rendering layer that passively observes actor signals
+and renders UI components via @xmachines/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.
 
+**Standard usage:**
+
+```tsx
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+	<PlayRenderer />
+</PlayUIProvider>
+```
+
+**Escape hatch (custom composition):**
+
+```tsx
+<ActorProvider actor={actor} registryResult={registryResult}>
+	<JSONUIProvider registry={registryResult.registry}>
+		<PlayRenderer />
+	</JSONUIProvider>
+</ActorProvider>
+```
+
 ## Classes
 
 - [PlayErrorBoundary](classes/PlayErrorBoundary.md)
 
 ## Interfaces
 
+- [ActionProviderProps](interfaces/ActionProviderProps.md)
+- [ActorProviderProps](interfaces/ActorProviderProps.md)
+- [ComponentContext](interfaces/ComponentContext.md)
+- [JSONUIProviderProps](interfaces/JSONUIProviderProps.md)
 - [PlayErrorBoundaryProps](interfaces/PlayErrorBoundaryProps.md)
 - [PlayErrorBoundaryState](interfaces/PlayErrorBoundaryState.md)
-- [PlayRendererProps](interfaces/PlayRendererProps.md)
+- [PlayUIProviderProps](interfaces/PlayUIProviderProps.md)
+- [RendererProps](interfaces/RendererProps.md)
+- [StateProviderProps](interfaces/StateProviderProps.md)
+- [ValidationProviderProps](interfaces/ValidationProviderProps.md)
+- [ViewContextValue](interfaces/ViewContextValue.md)
+- [VisibilityProviderProps](interfaces/VisibilityProviderProps.md)
+
+## Type Aliases
+
+- [AnyPlayActor](type-aliases/AnyPlayActor.md)
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [RenderErrorHandler](type-aliases/RenderErrorHandler.md)
 
 ## Variables
 
+- [ActorProvider](variables/ActorProvider.md)
 - [PlayRenderer](variables/PlayRenderer.md)
+- [PlayUIProvider](variables/PlayUIProvider.md)
 
 ## Functions
 
+- [ActionProvider](functions/ActionProvider.md)
+- [defineRegistry](functions/defineRegistry.md)
+- [JSONUIProvider](functions/JSONUIProvider.md)
+- [Renderer](functions/Renderer.md)
+- [StateProvider](functions/StateProvider.md)
+- [useActor](functions/useActor.md)
+- [useBoundProp](functions/useBoundProp.md)
+- [usePlayView](functions/usePlayView.md)
 - [useSignalEffect](functions/useSignalEffect.md)
+- [ValidationProvider](functions/ValidationProvider.md)
+- [VisibilityProvider](functions/VisibilityProvider.md)
+
+## References
+
+### PlayRendererProps
+
+Renames and re-exports [ActorProviderProps](interfaces/ActorProviderProps.md)