@xmachines/play-react 1.0.0-beta.46 → 1.0.0-beta.47

package/README.md

@@ -1,172 +1,54 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-react
 
-**React renderer for XMachines Play Architecture**
+React renderer for XMachines Play architecture with signal-driven rendering.
 
-Bridges TC39 Signal-driven actors to React's render cycle. Business logic stays in the actor; React is purely a rendering target.
+Part of the [xmachines-js monorepo](../../README.md).
 
-## Overview
+## Installation
 
-`@xmachines/play-react` provides `PlayRenderer`, a React component that:
+```bash
+npm install @xmachines/play-react
+```
 
-- 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)
+**Peer dependencies** (must be installed separately):
 
-Per [Play RFC](../docs/rfc/play.md):
+```bash
+npm install react react-dom xstate @xstate/store @json-render/react @json-render/core @json-render/xstate
+```
 
-- **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
+Supported versions:
 
-## Installation
+- `react` / `react-dom`: `^18.0.0 || ^19.0.0`
+- `xstate`: `^5.30.0`
+- `@xstate/store`: `^3.17.0`
+- `@json-render/*`: `^0.18.0`
 
-```bash
-npm install @xmachines/play-react
-npm install @json-render/react @json-render/core   # peer deps
-npm install @json-render/xstate @xstate/store      # store integration
-```
+## Usage
+
+### Standard usage — `PlayUIProvider` + `PlayRenderer`
 
-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.
-
-## Current Exports
-
-- `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
+The recommended pattern for actor-driven React rendering:
 
 ```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 — the contract between machine spec and UI components
-const catalog = defineCatalog({
-	elements: {
-		Login: { props: z.object({ title: z.string() }), description: "Login form" },
-		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
-	},
-});
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { definePlayer } from "@xmachines/play-xstate";
+
+// 1. Create and start the actor
+const actor = definePlayer({ machine: myMachine })();
+actor.start();
 
-// 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, {
+// 2. Define the component registry with action handlers
+const registryResult = defineRegistry(myCatalog, {
 	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" });
-		},
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
 
-// 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();
-
+// 3. Render — signals drive view transitions automatically
 function App() {
 	return (
 		<PlayUIProvider actor={actor} registryResult={registryResult}>
@@ -176,229 +58,136 @@ function App() {
 }
 ```
 
-## API Reference
+### With optional `JSONUIProvider` props
 
-### `PlayUIProvider`
-
-Batteries-included composite provider. Wraps `ActorProvider` + `JSONUIProvider`. Pass `actor` and `registryResult` here, then place `<PlayRenderer />` inside as a zero-prop child.
+Pass navigation and validation helpers through `PlayUIProvider`:
 
 ```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>
-```
-
-**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
-
-**`registryResult`** — Full result from `defineRegistry(catalog, { components, actions })`. Contains both the component registry and action handlers.
-
-**`store`** (optional) — Controls per-view UI state (form values, `$state` bindings):
-
-- **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.
-
-```tsx
-import { createAtom } from "@xstate/store";
-import { xstateStoreStateStore } from "@json-render/xstate";
-import type { StateStore } from "@json-render/core";
-
-const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "alice" }) });
-
-<PlayUIProvider actor={actor} registryResult={registryResult} store={store}>
-	<PlayRenderer />
-</PlayUIProvider>;
-```
-
-**`fallback`** — Shown when `actor.currentView.get()` is `null` (machine in a no-view state, or during initialisation).
-
-**`onError`** — Called when the outer `PlayErrorBoundary` catches an error. Receives `(error: Error, info: React.ErrorInfo)`. Use for observability tools (Sentry, Datadog, etc.).
-
-**`onRenderError`** — Called when an individual catalog component throws during render. Caught by `@json-render/react`'s inner per-element boundary — the failed component is silently removed while the rest of the spec continues rendering. `onError` / `fallback` are **not** triggered. When both `onRenderError` on `PlayUIProvider` and on `defineRegistry` are set, the prop wins.
-
----
-
-### `ActorProvider`
-
-Escape hatch primitive. Owns actor bridging, signal bridge, and store lifecycle. Use this when you need direct control over the provider layer (e.g. custom `JSONUIProvider` configuration).
-
-```tsx
-import { ActorProvider } from "@xmachines/play-react";
-
-<ActorProvider
 	actor={actor}
 	registryResult={registryResult}
-	onRenderError={(err, type) => reportError(err, type)}
->
-	{/* your own JSONUIProvider + PlayRenderer tree */}
-</ActorProvider>;
-```
-
----
-
-### `PlayRenderer`
-
-Zero-prop leaf component. Must be rendered inside a `PlayUIProvider` (or `ActorProvider`) tree. Subscribes to `actor.currentView` via context and renders the current spec.
-
-```tsx
-<PlayUIProvider actor={actor} registryResult={registryResult}>
-	<PlayRenderer />
-</PlayUIProvider>
-```
-
-`PlayRenderer` accepts no props — all configuration (`actor`, `registryResult`, `store`, `fallback`, `onError`, `onRenderError`) is provided by the enclosing `PlayUIProvider` or `ActorProvider`.
-
-## Error handling
-
-The provider tree has two layers of error boundaries:
-
-### Outer boundary — `onError` and `fallback`
-
-Wraps the entire renderer output via `PlayErrorBoundary`. Triggered when the spec or store setup throws, or when the inner boundary is not present.
-
-```tsx
-<PlayUIProvider
-	actor={actor}
-	registryResult={registryResult}
-	fallback={<p>Something went wrong.</p>}
-	onError={(err, info) => Sentry.captureException(err, { extra: info })}
+	navigate={(path) => router.push(path)}
+	validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
 >
 	<PlayRenderer />
 </PlayUIProvider>
 ```
 
-### Inner boundary — `onRenderError`
+### Escape hatch — custom provider composition
 
-Each catalog element is individually wrapped in an error boundary by `@json-render/react`. When a component throws, it is silently removed while the rest of the spec continues rendering. The outer boundary is **not** triggered.
-
-Pass `onRenderError` to `PlayUIProvider` (or `ActorProvider`) — overrides any registry-level handler — or bake it into `defineRegistry`:
+Use `ActorProvider` directly when you need to compose providers manually:
 
 ```tsx
-// via PlayUIProvider prop
-<PlayUIProvider
-	actor={actor}
-	registryResult={registryResult}
-	onRenderError={(error, elementType) => {
-		console.warn(`<${elementType}> crashed:`, error);
-	}}
->
-	<PlayRenderer />
-</PlayUIProvider>
-```
+import { ActorProvider, JSONUIProvider, PlayRenderer } from "@xmachines/play-react";
 
-```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);
-	},
-});
+<ActorProvider actor={actor} registryResult={registryResult}>
+	<JSONUIProvider registry={registryResult.registry}>
+		<PlayRenderer />
+	</JSONUIProvider>
+</ActorProvider>;
 ```
 
-`onRenderError` is typed as `RenderErrorHandler` and exported from.
-
----
-
-### `useActor`
-
-Hook for accessing the actor from inside any component rendered by `PlayRenderer`. No prop drilling needed.
+### Accessing the actor from inside the tree
 
 ```tsx
 import { useActor } from "@xmachines/play-react";
 
-// Works in any component rendered inside PlayRenderer:
-function LogoutButton() {
+function SubmitButton() {
 	const actor = useActor();
-	return <button onClick={() => actor.send({ type: "auth.logout" })}>Log Out</button>;
+	return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
 }
 ```
 
-Throws `NonNullableError: "useActor() must be called inside <ActorProvider> (or <PlayUIProvider>)"` if called outside the tree.
-
----
-
-### `useSignalEffect`
-
-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).
+### Subscribing to signals directly
 
 ```tsx
 import { useSignalEffect } from "@xmachines/play-react";
 
-function NavBar({ actor }: { actor: ReturnType<typeof createPlayer> }) {
-	const [isAuth, setIsAuth] = useState(false);
+function MyComponent({ actor }) {
+	const [view, setView] = useState(null);
 
 	useSignalEffect(() => {
-		const snap = actor.state.get();
-		setIsAuth((snap.context as { isAuthenticated: boolean }).isAuthenticated);
+		setView(actor.currentView.get());
 	});
 
-	return <nav>{isAuth ? <LogoutBtn /> : <LoginBtn />}</nav>;
+	return <div>{view?.component}</div>;
 }
 ```
 
----
+## API Summary
 
-### `PlayErrorBoundary`
+### Components
 
-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.
+| 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.                                                                |
 
-`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.
+### Hooks
 
-```tsx
-import { PlayErrorBoundary } from "@xmachines/play-react";
+| Export                      | Description                                                                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useSignalEffect(callback)` | Subscribes to TC39 signal changes; re-runs the callback and forces a React re-render when any accessed signal changes. 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.                     |
 
-<PlayErrorBoundary
-	fallback={<p>Something went wrong.</p>}
-	onError={(err, info) => Sentry.captureException(err, { extra: info })}
->
-	<PlayUIProvider actor={actor} registryResult={registryResult}>
-		<PlayRenderer />
-	</PlayUIProvider>
-</PlayErrorBoundary>;
-```
+### 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>`                                                          |
+| `PlayActor`              | Type alias for `AbstractActor<AnyActorLogic>`                                                  |
+| `ViewContextValue`       | Value shape returned by `usePlayView()`                                                        |
+| `RenderErrorHandler`     | Error handler callback type for render errors                                                  |
 
-## Route Parameters in Props
+### Re-exports from `@json-render/react`
 
-When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
+`@xmachines/play-react` re-exports the full `@json-render/react` surface so consumers only need one import:
 
 ```ts
-// spec: { section: undefined, user: "alice" }
-// After play.route to /settings/profile → context.params = { section: "profile" }
-// Component receives: { section: "profile", user: "alice" }
+import {
+	defineRegistry,
+	useBoundProp,
+	JSONUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	Renderer,
+} from "@xmachines/play-react";
 ```
 
-Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
+## Key Principle
+
+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.
+
+## Testing
+
+Run unit tests (jsdom environment):
 
----
+```bash
+npm test -w @xmachines/play-react
+```
 
-## Error Handling
+Run tests with coverage:
 
-| 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 |
+```bash
+npm run test:coverage -w @xmachines/play-react
+```
 
----
+Run browser integration tests (requires Chromium):
 
-## Architecture Notes
+```bash
+npm run test:browser -w @xmachines/play-react
+```
 
-- 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
+Coverage thresholds: 80% lines, functions, branches, and statements.
 
-## Learn More
+## License
 
-- [Demo](examples/demo/README.md)
-- [React Router adapter](../play-react-router/README.md)
-- [TanStack React Router adapter](../play-tanstack-react-router/README.md)
+MIT — see [LICENSE](./LICENSE).

package/package.json

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