@xmachines/docs 1.0.0-beta.33 → 1.0.0-beta.34

package/guides/signals.md

@@ -0,0 +1,166 @@
+# Understanding TC39 Signals in XMachines
+
+TC39 Signals are the reactive substrate connecting actors to the outside world in XMachines. This page explains what they are, why XMachines uses them instead of observables or callbacks, and how the three Signal primitives map to distinct roles in the architecture.
+
+After reading this, you will understand why infrastructure never reads state directly from an actor — and what it does instead.
+
+---
+
+## What problem Signals solve
+
+When a state machine transitions, several things may need to react: the URL bar might update, a router might navigate, a renderer might swap views. The naive approach is to let each of those consumers call `actor.getSnapshot()` whenever they feel like it — or to have the actor call back into each consumer via callbacks.
+
+Both approaches break down:
+
+- **Polling** (`getSnapshot()` on a timer or event) is racy: consumers can observe inconsistent intermediate states during a transition sequence.
+- **Callbacks** create direct dependencies between the actor and infrastructure, violating the architectural invariant that business logic must not depend on runtime APIs.
+
+TC39 Signals solve this with a **push–pull model**:
+
+- The actor **pushes** state changes into signals synchronously on every transition.
+- Consumers **pull** computed values lazily from signals — only when they actually need the value.
+- Changes propagate **atomically**, so no consumer ever sees a half-updated state.
+
+This model is sometimes called _glitch-free reactivity_: intermediate invalid states never escape to the environment.
+
+---
+
+## The three Signal primitives
+
+XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via `@xmachines/play-signals`:
+
+### `Signal.State` — writable values
+
+`Signal.State<T>` holds a single mutable value. Only the actor (or code it explicitly delegates to) writes to it. Everything else reads from it.
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+
+count.set(1); // write
+count.get(); // read → 1
+```
+
+In XMachines, `actor.state` is a `Signal.State<Snapshot>`. The actor updates it on every XState transition. Infrastructure reads it — never writes it.
+
+### `Signal.Computed` — derived values
+
+`Signal.Computed<T>` derives a value from one or more other signals. It recomputes only when its dependencies change — and only when something reads it (lazy evaluation).
+
+```typescript
+const route = new Signal.Computed(() => {
+	const snapshot = actor.state.get();
+	return snapshot.getMeta()?.route ?? null;
+});
+```
+
+In XMachines, `actor.currentRoute` is a `Signal.Computed<string | null>`. Router adapters read it to know which URL to push — they do not compute the route themselves. Route derivation stays in the actor where the business logic lives.
+
+### `Signal.subtle.Watcher` — reactive observation
+
+`Signal.subtle.Watcher` is the low-level primitive for reacting to signal changes. When a watched signal's value changes, the watcher's `notify` callback fires synchronously. You then schedule the actual work with `queueMicrotask` to avoid re-entrant signal reads.
+
+```typescript
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		for (const signal of pending) {
+			signal.get(); // re-read to flush
+		}
+		watcher.watch(...pending); // re-arm for next change
+	});
+});
+
+watcher.watch(actor.currentRoute);
+actor.currentRoute.get(); // initial read required to arm the watcher
+```
+
+Watcher notifications are **one-shot**: if you do not call `watch()` again after draining pending signals, you will miss subsequent changes.
+
+Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the `watchSignal()` helper covers the common case.
+
+---
+
+## `watchSignal()` — the safe helper
+
+`@xmachines/play-signals` exports `watchSignal(signal, onValue)` as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
+
+```typescript
+import { watchSignal } from "@xmachines/play-signals";
+
+const stop = watchSignal(actor.currentRoute, (route) => {
+	console.log("Route is now:", route);
+});
+
+// Later — stops observing and prevents use-after-free
+stop();
+```
+
+`watchSignal()` handles three subtle correctness concerns for you:
+
+| Concern                | What happens without it                            | How `watchSignal` handles it                                           |
+| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                       |
+| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst |
+| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                            |
+
+Use `watchSignal()` in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
+
+---
+
+## Why not observables (RxJS) or event emitters?
+
+The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:
+
+**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind `@xmachines/play-signals` means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
+
+**2. Synchronous atomic propagation.** RxJS streams are asynchronous by default. Event emitters fire immediately but serially — a listener registered halfway through a sequence can see inconsistent state. Signals propagate atomically: all computeds update before any watcher fires.
+
+**3. Pull-based evaluation.** Observables push values to every subscriber immediately. Signals are lazy: `Signal.Computed` does not recompute until something reads it. An adapter that is not currently mounted does not pay the cost of computing derived values.
+
+---
+
+## The five Signal invariants in XMachines
+
+The Play RFC defines five invariants that govern how signals are used:
+
+| Invariant                          | What it means in practice                                                                                   |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **INV-01: Actor Authority**        | Only actor code writes to `actor.state`. Never write to it from infrastructure.                             |
+| **INV-04: Passive Infrastructure** | Routers and renderers read signals and forward events. They never decide state transitions.                 |
+| **INV-05: Signal-Only Reactivity** | Cross-boundary communication uses signals. Infrastructure does not poll `getSnapshot()`.                    |
+| **INV-03: No Direct Queries**      | Infrastructure reads from signals, not from snapshot methods, outside of actor code.                        |
+| **INV-02: Strict Separation**      | Business logic (`machine` definition) never imports browser APIs, routing libraries, or framework packages. |
+
+---
+
+## Cleanup is mandatory
+
+Signals do not clean themselves up when they go out of scope. Every watcher you create must be explicitly disposed when the consuming component or adapter unmounts.
+
+- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by `watchSignal()`.
+- Router bridge `disconnect()` methods must unwatch all signal subscriptions.
+- If you use the raw `Signal.subtle.Watcher` API, pair every `watch()` call with `unwatch()` in teardown.
+
+Failing to clean up watchers causes memory leaks and stale callbacks firing after the consumer is gone.
+
+---
+
+## Summary
+
+| Primitive               | Role in XMachines                              | Who uses it                        |
+| ----------------------- | ---------------------------------------------- | ---------------------------------- |
+| `Signal.State`          | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
+| `Signal.Computed`       | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
+| `Signal.subtle.Watcher` | Low-level reactive observation                 | Framework adapters, router bridges |
+| `watchSignal()`         | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
+
+## See also
+
+- [Understanding the Actor Model](concepts-actor-model.md) — why the actor owns all signal writes
+- [Understanding State Machines](concepts-state-machines.md) — how state nodes produce the metadata that signals derive
+- [Getting Started](getting-started.md) — hands-on walkthrough using signals to observe an actor
+- [@xmachines/play-signals README](../api/@xmachines/play-signals/README.md) — API reference
+- [Play RFC](../rfc/play.md) — architectural specification
+- [TC39 Signals proposal](https://github.com/tc39/proposal-signals) — upstream proposal

package/guides/state-machines.md

@@ -0,0 +1,288 @@
+# Understanding State Machines in XMachines
+
+XMachines uses XState v5 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
+
+After reading this, you will understand what a machine definition actually encodes — and why state machines are a better unit of business logic than component-level state or ad-hoc if/else trees.
+
+---
+
+## What a finite state machine is
+
+A finite state machine (FSM) is a model of computation with three properties:
+
+1. **It is always in exactly one state** from a finite set of possible states.
+2. **It transitions between states only in response to events**.
+3. **The same event in different states can produce different outcomes** (or no transition at all).
+
+These three properties, taken together, make behavior _deterministic and exhaustive_. You cannot end up in an unlisted state. You cannot receive an event that produces an unspecified outcome — unhandled events are simply ignored.
+
+In traditional component-level state (e.g., boolean flags, `useState` combinations), you typically end up managing _n_ booleans for _n_ conditions. With _n_ booleans, you have 2^n possible combinations — and only a handful of them are actually valid. State machines force you to enumerate only the valid states.
+
+**Example:** A login flow with two booleans (`isLoading`, `isError`) has four combinations: `{false,false}`, `{true,false}`, `{false,true}`, `{true,true}`. The last one — loading and error simultaneously — is impossible in practice, but the code has no way to rule it out. A state machine with states `idle | loading | success | error` makes the impossible unrepresentable.
+
+---
+
+## How XMachines uses XState v5
+
+XMachines wraps XState v5 via `@xmachines/play-xstate`. You define machines using XState's `setup().createMachine()` API:
+
+```typescript
+import { setup } from "xstate";
+
+const authSetup = setup({
+	types: {
+		context: {} as { username: string | null },
+		events: {} as { type: "auth.login"; username: string } | { type: "auth.logout" },
+		input: {} as undefined,
+	},
+});
+
+const authMachine = authSetup.createMachine({
+	id: "auth",
+	initial: "unauthenticated",
+	context: { username: null },
+	states: {
+		unauthenticated: {
+			on: {
+				"auth.login": {
+					target: "authenticated",
+					actions: authSetup.assign({
+						username: ({ event }) => event.username,
+					}),
+				},
+			},
+		},
+		authenticated: {
+			on: {
+				"auth.logout": {
+					target: "unauthenticated",
+					actions: authSetup.assign({ username: null }),
+				},
+			},
+		},
+	},
+});
+```
+
+Key patterns:
+
+- **Always use `setup({ types })`** before `createMachine`. The type declarations let TypeScript check that your events, context fields, and actions are consistent throughout the machine.
+- **Use `setup.assign()`**, not the bare `assign` from xstate. This keeps the type checker aware of which context fields the action touches.
+- **Event names use lowercase dot-separated namespaces**: `"auth.login"`, `"play.route"`, `"form.submit"`. This convention makes the event log readable and avoids collisions.
+
+---
+
+## State node metadata: routing and views
+
+XMachines extends XState's `meta` field on each state node. This is where routing intent and view structure live:
+
+```typescript
+import { typedSpec } from "@xmachines/play-actor";
+
+const appMachine = setup({
+	/* ... */
+}).createMachine({
+	id: "app",
+	initial: "home",
+	states: {
+		home: {
+			meta: {
+				route: "/",
+				view: typedSpec({
+					root: "root",
+					elements: {
+						root: { type: "HomePage", props: { title: "Welcome" }, children: [] },
+					},
+				}),
+			},
+		},
+		login: {
+			meta: {
+				route: "/login",
+				view: typedSpec({
+					root: "root",
+					elements: {
+						root: { type: "LoginPage", props: { title: "Sign in" }, children: [] },
+					},
+				}),
+			},
+		},
+		dashboard: {
+			meta: {
+				route: "/dashboard",
+				view: typedSpec({
+					root: "root",
+					elements: {
+						root: { type: "DashboardPage", props: { title: "Overview" }, children: [] },
+					},
+				}),
+			},
+		},
+	},
+});
+```
+
+`meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
+
+`meta.view` is a `PlaySpec` — a `@json-render/core` spec object describing what to render. Use `typedSpec<TContext>(...)` from `@xmachines/play-actor` to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
+
+**The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
+
+---
+
+## `formatPlayRouteTransitions` — automatic route event wiring
+
+For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
+
+```typescript
+// Without formatPlayRouteTransitions — verbose and repetitive
+states: {
+  home: {
+    on: {
+      "play.route": [
+        { guard: ({ event }) => event.to === "#login", target: "login" },
+        { guard: ({ event }) => event.to === "#dashboard", target: "dashboard" },
+      ],
+    },
+    meta: { route: "/" },
+  },
+  // ... repeated for every state
+}
+```
+
+`formatPlayRouteTransitions` from `@xmachines/play-xstate` generates these transitions automatically from the `id` and `meta.route` fields you already have:
+
+```typescript
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+
+const appMachine = setup({
+	/* ... */
+}).createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			login: { id: "login", meta: { route: "/login" } },
+			dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+		},
+	}),
+);
+```
+
+`formatPlayRouteTransitions` inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+
+```typescript
+types: {
+  context: {} as {
+    params: Record<string, string>;
+    query:  Record<string, string>;
+    // ... other context fields
+  },
+  events: {} as PlayRouteEvent | OtherEvents,
+}
+```
+
+---
+
+## Guards — the actor's authority
+
+Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of `{ context, event }` that return a boolean.
+
+```typescript
+const authSetup = setup({
+	guards: {
+		isAuthenticated: ({ context }) => context.isAuthenticated,
+		isAdmin: ({ context }) => context.role === "admin",
+	},
+});
+```
+
+Guards are evaluated by XState before a transition fires. If the guard returns `false`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
+
+This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
+
+XMachines provides guard combinators in `@xmachines/play-xstate` for composing complex conditions:
+
+| Function                          | What it does                            |
+| --------------------------------- | --------------------------------------- |
+| `composeGuards(...guards)`        | AND — all guards must pass              |
+| `composeGuardsOr(...guards)`      | OR — any guard must pass                |
+| `negateGuard(guard)`              | NOT — inverts the guard result          |
+| `hasContext(key)`                 | Checks that a context field is non-null |
+| `contextFieldMatches(key, value)` | Checks a context field against a value  |
+| `eventMatches(type)`              | Checks the event type                   |
+
+---
+
+## Context — persistent state across transitions
+
+Context is the machine's persistent data store. It survives transitions and can be read and updated by actions:
+
+```typescript
+// Context is defined in setup({ types })
+types: {
+  context: {} as {
+    isAuthenticated: boolean;
+    username: string | null;
+    loginAttempts: number;
+  },
+},
+
+// Actions mutate context via assign
+actions: {
+  recordLoginFailure: assign({
+    loginAttempts: ({ context }) => context.loginAttempts + 1,
+  }),
+},
+```
+
+Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
+
+---
+
+## Snapshots and restoration
+
+A snapshot is a point-in-time serialisation of the machine's current state and context. XState produces snapshots in a JSON-compatible format:
+
+```typescript
+const snapshot = actor.getSnapshot();
+// snapshot.value → current state node name, e.g. "dashboard"
+// snapshot.context → current context object
+
+// Stop and serialize
+actor.stop();
+const saved = JSON.stringify(snapshot);
+
+// Restore
+const restored = JSON.parse(saved);
+const actor = createPlayer(undefined, { snapshot: restored });
+actor.start();
+// Actor resumes from where it left off
+```
+
+`definePlayer` accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+
+---
+
+## What state machines replace
+
+| Traditional pattern                                   | State machine equivalent                     | Why the machine version is better                           |
+| ----------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
+| Boolean flags (`isLoading`, `isError`)                | Explicit states (`idle \| loading \| error`) | Impossible state combinations are unrepresentable           |
+| Switch on URL path in component                       | `meta.route` on state nodes                  | Routing intent lives with the state that owns it            |
+| `if (user.role === "admin")` scattered in components  | Guards on transitions                        | Auth logic is co-located with the transitions it governs    |
+| `useEffect` on route changes to decide what to render | `meta.view` on state nodes                   | View structure is declared alongside the state that owns it |
+| Shared mutable state across components                | Context + signals                            | Mutations are explicit, traceable, and test-covered         |
+
+---
+
+## See also
+
+- [Understanding the Actor Model](actor-model.md) — how the machine definition becomes a live actor
+- [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
+- [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
+- [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
+- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — full API reference for `definePlayer`, `PlayerActor`, guard combinators
+- [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
+- [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.33",
+  "version": "1.0.0-beta.34",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -49,7 +49,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.33",
+    "@xmachines/shared": "1.0.0-beta.34",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0",
     "typedoc": "^0.28.19",

package/rfc/play.md

@@ -156,13 +156,8 @@ export interface PlaySpec extends Spec {
 	contextProps?: string[];
 }
 
-export interface ViewMetadata {
-	component: string;
-	spec: PlaySpec;
-}
-
 export interface Viewable {
-	readonly currentView: Signal.State<ViewMetadata | null>;
+	readonly currentView: Signal.State<PlaySpec | null>;
 }
 
 // The Base Protocol — minimal contract
@@ -231,7 +226,7 @@ class PlayerActor<TMachine extends AnyStateMachine>
 {
 	public state: Signal.State<AnyMachineSnapshot>;
 	public currentRoute: Signal.Computed<string | null>;
-	public currentView: Signal.State<ViewMetadata | null>;
+	public currentView: Signal.State<PlaySpec | null>;
 	public readonly initialRoute: string | null;
 }
 ```
@@ -317,27 +312,44 @@ Each view renderer provides a `PlayRenderer` component that passively observes t
 **`@xmachines/play-react` exports (representative):**
 
 ```ts
-// Main component
-export const PlayRenderer: React.FC<PlayRendererProps> = ({
-  actor,     // AbstractActor & Viewable
-  registry,  // ComponentRegistry from defineRegistry()
-  store?,    // Optional external StateStore (controlled mode)
-  fallback?, // Shown when currentView is null
-  actions?,  // Map of action names → XState event type strings
-}) => { /* ... */ };
+// Batteries-included composite — standard entry point
+// Props: actor, registryResult, store?, fallback?, onError?, onRenderError?,
+//        validationFunctions?, navigate?, functions?
+export { PlayUIProvider } from "./PlayUIProvider";
+export type { PlayUIProviderProps } from "./PlayUIProvider";
+
+// Escape-hatch primitive — owns actor lifecycle, signal bridge, ViewContext
+// Props: actor, registryResult, store?, fallback?, onError?, onRenderError?, children (required)
+export { ActorProvider } from "./ActorProvider";
+export type { ActorProviderProps } from "./ActorProvider";
+
+// Zero-prop leaf — reads usePlayView() from ActorProvider tree; renders <Renderer spec={...} />
+// Must be rendered inside <ActorProvider> or <PlayUIProvider>
+export const PlayRenderer: React.FC = () => {
+	/* ... */
+};
 
 // Hooks
-export { useSignalEffect } from './useSignalEffect';
-export { useActor } from './useActor';
+export { usePlayView } from "./ActorProvider"; // returns ViewContextValue | null
+export { useSignalEffect } from "./useSignalEffect";
+export { useActor } from "./useActor";
 
 // Error handling
-export { PlayErrorBoundary } from './PlayErrorBoundary';
+export { PlayErrorBoundary } from "./PlayErrorBoundary";
 
 // Re-exports from @json-render/react
-export { defineRegistry, useStateBinding, useBoundProp } from '@json-render/react';
+export {
+	defineRegistry,
+	JSONUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	Renderer,
+} from "@json-render/react";
 ```
 
-**Design Rationale:** The original design passed `components: ComponentMap<TCatalog>` and `catalog: Catalog` directly to `PlayRenderer`. The implementation replaced these with a single `registry` (from `defineRegistry`), which bakes catalog validation into the registry at definition time. This eliminates runtime catalog lookups and provides better TypeScript inference.
+**Design Rationale:** `PlayRenderer` is now a **zero-prop leaf component** — it reads view context from the enclosing `ActorProvider` via `usePlayView()`. All mount-time concerns (actor bridging, signal subscription, store lifecycle, `onRenderError` injection) are centralised in `ActorProvider`. `PlayUIProvider` is the batteries-included composite that wraps `ActorProvider` + `JSONUIProvider` with a handler bridge. This mirrors the provider/renderer split in `@json-render/*` and makes the separation of concerns explicit.
 
 ### 5.5 Schema Layer (External)
 
@@ -383,11 +395,17 @@ export const machine = setup({
 		overview: {
 			meta: {
 				route: "/dashboard",
-				view: {
-					type: "Dashboard",
-					props: { title: "Q4 Performance" },
-					children: [{ type: "Metric", props: { value: 100, label: "Sales" } }],
-				},
+				view: typedSpec<DashboardCtx>({
+					root: "root",
+					elements: {
+						root: {
+							type: "Dashboard",
+							props: { title: "Q4 Performance" },
+							children: ["metric"],
+						},
+						metric: { type: "Metric", props: { value: 100, label: "Sales" } },
+					},
+				}),
 			},
 		},
 	},
@@ -404,7 +422,7 @@ Binds Logic to a View Renderer and Router Adapter.
 ```tsx
 import { createDashboard, machine } from "./features/dashboard/player";
 import { catalog } from "./catalog";
-import { PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
 
@@ -412,13 +430,18 @@ import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
 const actor = createDashboard();
 
 // 2. Define component implementations (type-checked against catalog)
-const registry = defineRegistry(catalog, {
-	Dashboard: ({ props, children }) => <div className="p-4">{children}</div>,
-	Metric: ({ props }) => (
-		<span>
-			{props.label}: {props.value}
-		</span>
-	),
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Dashboard: ({ props, children }) => <div className="p-4">{children}</div>,
+		Metric: ({ props }) => (
+			<span>
+				{props.label}: {props.value}
+			</span>
+		),
+	},
+	actions: {
+		submit: async () => actor.send({ type: "form.submit" }),
+	},
 });
 
 // 3. Build route map from machine definition
@@ -429,9 +452,13 @@ const routeMap = createRouteMap(routeTree);
 const bridge = new TanStackReactRouterBridge(tanstackRouter, actor, routeMap);
 bridge.connect();
 
-// 5. Render
+// 5. Render — PlayUIProvider is the batteries-included composite; PlayRenderer is the zero-prop leaf
 function App() {
-	return <PlayRenderer actor={actor} registry={registry} actions={{ submit: "form.submit" }} />;
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 

package/api/@xmachines/play-actor/interfaces/ViewMetadata.md

@@ -1,17 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-actor](../README.md) / ViewMetadata
-
-# Interface: ViewMetadata
-
-Defined in: [packages/play-actor/src/abstract-actor.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-actor/src/abstract-actor.ts#L100)
-
-View metadata for rendering.
-
-Describes the component to be rendered and the json-render Spec to use.
-Used by PlayRenderer to dynamically render UI based on actor state.
-
-## Properties
-
-| Property                                    | Type                      | Description                                                                                                                                                                                                                                | Defined in                                                                                                                                                       |
-| ------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-component"></a> `component` | `string`                  | Root element type name (for diagnostics and component resolution)                                                                                                                                                                          | [packages/play-actor/src/abstract-actor.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-actor/src/abstract-actor.ts#L102) |
-| <a id="property-spec"></a> `spec`           | [`PlaySpec`](PlaySpec.md) | XMachines view spec — extends `@json-render/core` Spec with `contextProps` for explicit context field exposure. Use `typedSpec<TContext>(...)` at the definition site to validate `contextProps` entries against the machine context type. | [packages/play-actor/src/abstract-actor.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-actor/src/abstract-actor.ts#L110) |