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

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.35",
   "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.35",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0",
     "typedoc": "^0.28.19",

package/rfc/play.md

@@ -20,24 +20,24 @@ The reference implementation provides a modular monorepo that satisfies the arch
 ### 2.1 Roles
 
 - **The Actor (Logic Engine)**
-  - Pure, environment-agnostic logic runtime
-  - Owns state, guards, errors, and route validity
-  - Emits _Virtual Routes_ as derived intent
+    - Pure, environment-agnostic logic runtime
+    - Owns state, guards, errors, and route validity
+    - Emits _Virtual Routes_ as derived intent
 
 - **The Runtime Adapter (Infrastructure Layer)**
-  - Environment-specific adapter (Browser, Native, Server, Test Runner)
-  - Reflects Actor output into the environment
-  - Forwards environment events to the Actor without interpretation
+    - Environment-specific adapter (Browser, Native, Server, Test Runner)
+    - Reflects Actor output into the environment
+    - Forwards environment events to the Actor without interpretation
 
 - **The View**
-  - Passive consumer of Actor state
-  - No business rules or routing authority
+    - Passive consumer of Actor state
+    - No business rules or routing authority
 
 ### 2.2 Communication Medium
 
 - **Signals (TC39 Proposal)**
-  - Used exclusively for Actor ↔ Adapter communication
-  - Enables synchronous, glitch-free propagation
+    - Used exclusively for Actor ↔ Adapter communication
+    - Enables synchronous, glitch-free propagation
 
 ---
 
@@ -75,9 +75,9 @@ The reference implementation provides a modular monorepo that satisfies the arch
 - Defines **Virtual Routes** as metadata on state nodes
 - Validates all incoming navigation intents
 - On invalid intent:
-  1. Transitions to an error or fallback state
-  2. Emits a corresponding Virtual Route (e.g. `/error`, `/login`)
-  3. Forces the environment to realign with Actor state
+    1. Transitions to an error or fallback state
+    2. Emits a corresponding Virtual Route (e.g. `/error`, `/login`)
+    3. Forces the environment to realign with Actor state
 
 The Actor has zero knowledge of:
 
@@ -114,9 +114,9 @@ Wraps the TC39 Signals (Stage 1) polyfill. By isolating the reactive primitive w
 **Exports:**
 
 - `Signal` — Re-exported namespace from `signal-polyfill`:
-  - `Signal.State` — Actor output snapshot
-  - `Signal.Computed` — Lazy, pull-based derivation of routes and views
-  - `Signal.subtle.Watcher` — Synchronous observation for Runtime Adapters
+    - `Signal.State` — Actor output snapshot
+    - `Signal.Computed` — Lazy, pull-based derivation of routes and views
+    - `Signal.subtle.Watcher` — Synchronous observation for Runtime Adapters
 - `watchSignal` — Convenience function: subscribes to a single signal with a one-shot watcher lifecycle and microtask batching; returns a cleanup function
 
 #### 5.1.2 `@xmachines/play`
@@ -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;
 }
 ```
@@ -251,9 +246,9 @@ Provides the complete routing infrastructure: route extraction from state machin
 - `RouterBridge` — Interface: `{ connect(): void; disconnect(): void }`
 - `PlayRouteEvent` — Routing event: `{ type: 'play.route'; to: string; params?; query?; match? }`
 - `RouterBridgeBase` — Abstract base class that encapsulates common bridge logic (signal watching, route synchronization, param/query extraction). Subclasses implement only three methods:
-  - `navigateRouter(path)` — Push a path into the framework router
-  - `watchRouterChanges()` — Subscribe to framework router navigation events
-  - `unwatchRouterChanges()` — Unsubscribe from framework router events
+    - `navigateRouter(path)` — Push a path into the framework router
+    - `watchRouterChanges()` — Subscribe to framework router navigation events
+    - `unwatchRouterChanges()` — Unsubscribe from framework router events
 
 **Route Extraction Exports:**
 
@@ -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) |

package/api/@xmachines/play-react/interfaces/PlayRendererProps.md

@@ -1,24 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-react](../README.md) / PlayRendererProps
-
-# Interface: PlayRendererProps\<TLogic\>
-
-Defined in: [packages/play-react/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L27)
-
-Props for PlayRenderer component
-
-## Type Parameters
-
-| Type Parameter                                                                           | Default type                                                          | Description                                                                     |
-| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | The XState actor logic type. Defaults to `AnyActorLogic` for non-generic usage. |
-
-## Properties
-
-| Property                                              | Type                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                           | Defined in                                                                                                                                   |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                                                                                                                                                 | [packages/play-react/src/types.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L29) |
-| <a id="property-fallback"></a> `fallback?`            | `ReactNode`                                                                                                                                                                                         | Optional component shown when currentView is null                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-react/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L60) |
-| <a id="property-onerror"></a> `onError?`              | (`error`, `info`) => `void`                                                                                                                                                                         | Optional callback invoked when a catalog component throws during render.                                                                                                                                                                                                                                                                                                                                                              | [packages/play-react/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L72) |
-| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                       | Called when an individual catalog component throws during render. Caught by the inner error boundary inside each rendered element — the failed component is silently removed while the rest of the spec continues rendering. Unlike `onError`, this does not receive a reset callback. Takes precedence over any `onRenderError` set via `defineRegistry`. When not provided, `@json-render/react` logs the error to `console.error`. | [packages/play-react/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L84) |
-| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                              | Full result from defineRegistry() in @json-render/react. Contains both the component registry and the action handlers factory. Action handlers are real async functions dispatching to the actor (not string-mapped event types).                                                                                                                                                                                                     | [packages/play-react/src/types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L48) |
-| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                        | Optional external StateStore (controlled mode).                                                                                                                                                                                                                                                                                                                                                                                       | [packages/play-react/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-react/src/types.ts#L57) |

package/api/@xmachines/play-solid/interfaces/PlayRendererProps.md

@@ -1,24 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / PlayRendererProps
-
-# Interface: PlayRendererProps\<TLogic\>
-
-Defined in: [packages/play-solid/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L26)
-
-Props for PlayRenderer component
-
-## Type Parameters
-
-| Type Parameter                                                                           | Default type                                                          | Description                                                                     |
-| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `TLogic` _extends_ [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic) | The XState actor logic type. Defaults to `AnyActorLogic` for non-generic usage. |
-
-## Properties
-
-| Property                                              | Type                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                           | Defined in                                                                                                                                   |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                   | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`TLogic`, [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability)                                                                                                                                                                                                                                                                                                                                                                 | [packages/play-solid/src/types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L28) |
-| <a id="property-fallback"></a> `fallback?`            | `any`                                                                                                                                                                                               | Optional element shown when currentView is null or a component throws                                                                                                                                                                                                                                                                                                                                                                 | [packages/play-solid/src/types.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L38) |
-| <a id="property-onerror"></a> `onError?`              | (`error`) => `void`                                                                                                                                                                                 | Optional callback invoked when a catalog component throws during render.                                                                                                                                                                                                                                                                                                                                                              | [packages/play-solid/src/types.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L45) |
-| <a id="property-onrendererror"></a> `onRenderError?`  | [`RenderErrorHandler`](../type-aliases/RenderErrorHandler.md)                                                                                                                                       | Called when an individual catalog component throws during render. Caught by the inner error boundary inside each rendered element — the failed component is silently removed while the rest of the spec continues rendering. Unlike `onError`, this does not receive a reset callback. Takes precedence over any `onRenderError` set via `defineRegistry`. When not provided, `@json-render/solid` logs the error to `console.error`. | [packages/play-solid/src/types.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L57) |
-| <a id="property-registryresult"></a> `registryResult` | `DefineRegistryResult`                                                                                                                                                                              | Full result from defineRegistry() in @json-render/solid. Contains both the component registry and the action handlers factory. Action handlers are real async functions dispatching to the actor (not string-mapped event types).                                                                                                                                                                                                     | [packages/play-solid/src/types.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L35) |
-| <a id="property-store"></a> `store?`                  | `StateStore`                                                                                                                                                                                        | Optional external StateStore (e.g. from `xstateStoreStateStore` in @json-render/xstate). When provided, PlayRenderer operates in controlled mode — spec.state is ignored and this store is the single source of truth for UI state (form values, etc.). When omitted, a fresh @xstate/store atom is created internally per view transition, seeded from spec.state.                                                                   | [packages/play-solid/src/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.33/packages/play-solid/src/types.ts#L66) |