@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.17

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

@@ -2,422 +2,343 @@
 
 # @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`)
+**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
 
-**Behavior:**
+**`registry`** — Built with `defineRegistry(catalog, { components, actions })` from `@xmachines/play-react`.
 
-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
+**`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:
 
-**Example:**
-
-```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:**
+**`store`** (optional) — Controls per-view UI state (form values, `$state` bindings):
 
-- 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`
+- **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.
 
-**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()`
-
-Watcher notification is one-shot, so re-arm and explicit cleanup are both required.
-
-**Example:**
-
-```typescript
-import { useSignalEffect } from "@xmachines/play-react";
-import { useState } from "react";
+```tsx
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate";
+import type { StateStore } from "@json-render/core";
 
-function RouteDisplay({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
+const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "alice" }) });
 
-	useSignalEffect(() => {
-		const currentRoute = actor.currentRoute.get();
-		setRoute(currentRoute);
-	});
-
-	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
-
-```typescript
-import { PlayRenderer } from "@xmachines/play-react";
-import { defineCatalog } from "@xmachines/play-catalog";
-import { z } from "zod";
+### `useSignalEffect`
 
-// 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} />;
-```
+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).
 
-### 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";
+---
 
-// 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>
-				);
-			}}
-		/>
-	);
-}
+### `PlayErrorBoundary`
 
-// Header component also receives actor
-function Header({ actor }: { actor: AbstractActor<any> }) {
-	const [route, setRoute] = useState<string | null>(null);
+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.
 
-	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
+## Route Parameters in Props
 
-2. **Signals as Source of Truth:**
-    - `actor.currentView.get()` provides UI structure
-    - `actor.currentRoute.get()` provides navigation state
-    - Components observe signals via `useSignalEffect`
+When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
 
-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
-
-4. **Microtask Batching:**
-    - `Signal.subtle.Watcher` coalesces rapid signal changes
-    - Prevents React thrashing from multiple signal updates
-    - Single React render per microtask batch
-
-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/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
+| 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`
 
 @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.
+
 ## Classes
 
 - [PlayErrorBoundary](classes/PlayErrorBoundary.md)
 
 ## Interfaces
 
+- [ComponentContext](interfaces/ComponentContext.md)
 - [PlayErrorBoundaryProps](interfaces/PlayErrorBoundaryProps.md)
 - [PlayErrorBoundaryState](interfaces/PlayErrorBoundaryState.md)
 - [PlayRendererProps](interfaces/PlayRendererProps.md)
 
+## Type Aliases
+
+- [ComponentFn](type-aliases/ComponentFn.md)
+- [PlayActor](type-aliases/PlayActor.md)
+
 ## Variables
 
 - [PlayRenderer](variables/PlayRenderer.md)
 
 ## Functions
 
+- [defineRegistry](functions/defineRegistry.md)
+- [useActor](functions/useActor.md)
 - [useSignalEffect](functions/useSignalEffect.md)
+- [~~useStateBinding~~](functions/useStateBinding.md)