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

package/README.md

@@ -1,169 +1,56 @@
-# @xmachines/play-solid
-
-**Solid renderer for XMachines Play Architecture**
-
-Bridges TC39 Signal-driven actors to Solid's fine-grained reactivity. Business logic stays in the actor; Solid is purely a rendering target.
-
-## Overview
+<!-- generated-by: gsd-doc-writer -->
 
-`@xmachines/play-solid` provides `PlayRenderer`, a Solid component that:
+# @xmachines/play-solid
 
-- Subscribes to `actor.currentView` (TC39 Signal) and re-renders on every state transition
-- Renders the current view's JSON spec via `@json-render/solid`
-- 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)
+> Solid renderer for XMachines Play architecture
 
-Per [Play RFC](../docs/rfc/play.md):
+SolidJS rendering layer that passively observes actor signals and renders UI components via `@json-render/solid`. SolidJS reactivity is used solely to trigger re-renders — TC39 Signals are the source of truth.
 
-- **Actor Authority (INV-01):** Guards in the machine decide all state transitions
-- **Passive Infrastructure (INV-04):** Solid observes signals and dispatches events — never decides
-- **Signal-Only Reactivity (INV-05):** `actor.currentView` signal is the sole render trigger
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
 npm install @xmachines/play-solid
-npm install @json-render/solid @json-render/core   # peer deps
-npm install @json-render/xstate @xstate/store      # store integration
 ```
 
-In this monorepo, the root install applies a `patch-package` patch to `@json-render/solid`
-so `defineRegistry(..., { onRenderError })` can intercept inner element-boundary errors
-without muting console output.
-
-## Current Exports
-
-- `PlayRenderer` — main renderer component
-- `useActor` — hook for accessing the actor inside a `PlayRenderer` tree
-- `defineRegistry` — re-exported from `@json-render/solid`
-- `useBoundProp` — re-exported from `@json-render/solid`
-- `ComponentFn` (type) — re-exported from `@json-render/solid`
-- `ComponentContext` (type) — re-exported from `@json-render/solid`
-- `ActorProvider` — escape hatch primitive (owns actor bridging, signal bridge, store lifecycle)
-- `PlayUIProvider` — batteries-included composite (wraps `ActorProvider` + `JSONUIProvider`)
-- `usePlayView` — hook for accessing the current view spec inside a provider tree
-- `RenderErrorHandler` (type) — inner per-element error callback signature
-- `ActorProviderProps` (type)
-- `ViewContextValue` (type)
-- `PlayActor` (type)
+**Peer dependencies** — install alongside the package:
+
+```bash
+npm install solid-js xstate @xstate/store @json-render/solid @json-render/core @json-render/xstate
+```
 
 ## Quick Start
 
 ```tsx
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import { PlayRenderer } from "@xmachines/play-solid";
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+import { definePlayer } from "@xmachines/play-xstate";
 import { defineCatalog } from "@json-render/core";
-import { defineRegistry } from "@xmachines/play-solid";
-import type { ComponentFn } from "@xmachines/play-solid";
-import { setup, assign } from "xstate";
-import { z } from "zod";
-
-// 1. Define catalog — the contract between machine spec and UI components
-const catalog = defineCatalog({
-	elements: {
-		Login: { props: z.object({ title: z.string() }), description: "Login form" },
-		Dashboard: { props: z.object({ username: z.string() }), description: "Dashboard" },
+import { schema } from "@json-render/solid/schema";
+
+// 1. Define a catalog
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({}), description: "Home screen" },
+		Login: { props: z.object({ error: z.string().optional() }), description: "Login screen" },
 	},
+	actions: {},
 });
 
-// 2. Implement components using ComponentFn — typed against catalog entries
-const Login: ComponentFn<typeof catalog, "Login"> = ({ props, emit }) => (
-	<div class="view">
-		<h2>{props.title}</h2>
-		<form
-			onSubmit={(e) => {
-				e.preventDefault();
-				emit("submit");
-			}}
-		>
-			<button type="submit">Log In</button>
-		</form>
-	</div>
-);
-
-const Dashboard: ComponentFn<typeof catalog, "Dashboard"> = ({ props }) => (
-	<div class="view">Welcome, {props.username}!</div>
-);
-
-// 3. Build registry
+// 2. Build a component registry
 const registryResult = defineRegistry(catalog, {
-	components: { Login, Dashboard },
-	actions: {
-		login: async (params) => {
-			if (!params) return;
-			actor.send({ type: "auth.login", username: params.username });
-		},
-		logout: async (params) => {
-			actor.send({ type: "auth.logout" });
-		},
+	components: {
+		Home: () => <div>Welcome home!</div>,
+		Login: (ctx) => <div>Login {ctx.props.error && <span>{ctx.props.error}</span>}</div>,
 	},
 });
 
-// 4. Define machine with view metadata
-const machine = setup({
-	types: {
-		context: {} as {
-			isAuthenticated: boolean;
-			username: string | null;
-			params: Record<string, string>;
-			query: Record<string, string>;
-		},
-		events: {} as
-			| { type: "auth.login"; username: string }
-			| { type: "auth.logout" }
-			| { type: "play.route"; to: string; params?: Record<string, string> },
-	},
-}).createMachine(
-	formatPlayRouteTransitions({
-		id: "app",
-		initial: "login",
-		context: { isAuthenticated: false, username: null, params: {}, query: {} },
-		states: {
-			login: {
-				id: "login",
-				meta: {
-					route: "/login",
-					view: {
-						root: "root",
-						elements: {
-							root: { type: "Login", props: { title: "Sign In" }, children: [] },
-						},
-					},
-				},
-			},
-			dashboard: {
-				id: "dashboard",
-				meta: {
-					route: "/dashboard",
-					view: {
-						root: "root",
-						elements: {
-							root: { type: "Dashboard", props: { username: "" }, children: [] },
-						},
-					},
-				},
-			},
-		},
-		on: {
-			"auth.login": {
-				target: ".dashboard",
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: assign({ isAuthenticated: true, username: ({ event }) => event.username }),
-			},
-			"auth.logout": {
-				target: ".login",
-				guard: ({ context }) => context.isAuthenticated,
-				actions: assign({ isAuthenticated: false, username: null }),
-			},
-		},
-	}),
-);
-
-// 5. Create actor and render
-const createPlayer = definePlayer({ machine });
+// 3. Create and start an actor
+const createPlayer = definePlayer({ machine: myMachine });
 const actor = createPlayer();
 actor.start();
 
+// 4. Render
 function App() {
 	return (
 		<PlayUIProvider actor={actor} registryResult={registryResult}>
@@ -173,178 +60,145 @@ function App() {
 }
 ```
 
-## API Reference
+## Usage
 
-### `PlayUIProvider`
+### `PlayUIProvider` + `PlayRenderer` (recommended)
 
-Batteries-included composite provider. Wraps `ActorProvider` + `JSONUIProvider`. Pass `actor` and `registryResult` here, then place `<PlayRenderer />` inside as a zero-prop child.
+`PlayUIProvider` is the batteries-included entry point. It wraps `ActorProvider` and `JSONUIProvider` into a single composite provider. `PlayRenderer` is a zero-prop leaf component that reads view context and renders the current spec.
 
 ```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+
 <PlayUIProvider
 	actor={actor}
 	registryResult={registryResult}
-	store={myStore}
-	fallback={<p>Loading…</p>}
-	onError={(err) => Sentry.captureException(err)}
-	onRenderError={(error, elementType) => console.warn(`<${elementType}> crashed:`, error)}
+	fallback={<div>Loading…</div>}
+	onError={(err) => console.error(err)}
+	navigate={navigateFn} // optional: passed to JSONUIProvider
+	validationFunctions={valFns} // optional: form validation helpers
 >
 	<PlayRenderer />
-</PlayUIProvider>
+</PlayUIProvider>;
 ```
 
-**`actor`** — A `PlayerActor` (or any `AbstractActor & Viewable`). Provides the `currentView` signal.
+### `ActorProvider` (escape hatch)
 
-**`registryResult`** — The full `DefineRegistryResult` returned by `defineRegistry(catalog, { components, actions })` from.
-
-**`store`** (optional) — Controls per-view UI state (`$state` bindings, form values):
-
-- **Omitted (uncontrolled, default):** A fresh `@xstate/store` atom is created per view transition, seeded from `view.spec.state`.
-- **Provided (controlled):** The caller owns the store; `spec.state` is ignored.
+For library authors who need direct control over provider composition:
 
 ```tsx
-import { createAtom } from "@xstate/store";
-import { xstateStoreStateStore } from "@json-render/xstate";
-import type { StateStore } from "@json-render/core";
+import { ActorProvider, PlayRenderer } from "@xmachines/play-solid";
 
-const store: StateStore = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
-
-<PlayUIProvider actor={actor} registryResult={registryResult} store={store}>
+<ActorProvider actor={actor} registryResult={registryResult}>
 	<PlayRenderer />
-</PlayUIProvider>;
+</ActorProvider>;
 ```
 
-**`fallback`** — Shown when `actor.currentView.get()` is `null`.
-
-**`onError`** — Called when the outer `ErrorBoundary` catches an error. Receives `(error: unknown)`. Use for observability tools.
-
-**`onRenderError`** — Called when an individual catalog component throws during render. Caught by `@json-render/solid`'s inner per-element `ErrorBoundary` — the failed component is silently removed while the rest of the spec continues rendering. `onError` / `fallback` are **not** triggered. When both `onRenderError` on `PlayUIProvider` and on `defineRegistry` are set, the prop wins.
-
----
+### `useActor` hook
 
-### `ActorProvider`
-
-Escape hatch primitive. Owns actor bridging, signal bridge, and store lifecycle. Use this when you need direct control over the provider layer.
+Access the raw actor instance anywhere inside an `ActorProvider` or `PlayUIProvider` tree:
 
 ```tsx
-import { ActorProvider } from "@xmachines/play-solid";
+import { useActor } from "@xmachines/play-solid";
 
-<ActorProvider
-	actor={actor}
-	registryResult={registryResult}
-	onRenderError={(err, type) => reportError(err, type)}
->
-	{/* your own JSONUIProvider + PlayRenderer tree */}
-</ActorProvider>;
+function SubmitButton() {
+	const actor = useActor();
+	return <button onClick={() => actor.send({ type: "SUBMIT" })}>Submit</button>;
+}
 ```
 
----
+### `usePlayView` hook
 
-### `PlayRenderer`
-
-Zero-prop leaf component. Must be rendered inside a `PlayUIProvider` (or `ActorProvider`) tree. Subscribes to `actor.currentView` via context and renders the current spec.
+Access the resolved view context (spec, handlers, registry) from within the provider tree:
 
 ```tsx
-<PlayUIProvider actor={actor} registryResult={registryResult}>
-	<PlayRenderer />
-</PlayUIProvider>
-```
+import { usePlayView } from "@xmachines/play-solid";
+import { Renderer } from "@json-render/solid";
 
-`PlayRenderer` accepts no props — all configuration (`actor`, `registryResult`, `store`, `fallback`, `onError`, `onRenderError`) is provided by the enclosing `PlayUIProvider` or `ActorProvider`.
-
-## Error handling
-
-The provider tree has two layers of error boundaries:
-
-### Outer boundary — `onError` and `fallback`
-
-Wraps the entire renderer via a SolidJS `ErrorBoundary`. Triggered when the spec or store setup throws, or when the inner boundary is not present.
-
-```tsx
-<PlayUIProvider
-	actor={actor}
-	registryResult={registryResult}
-	fallback={<p>Something went wrong.</p>}
-	onError={(err) => Sentry.captureException(err)}
->
-	<PlayRenderer />
-</PlayUIProvider>
+const MyRenderer = () => {
+	const view = usePlayView();
+	return <Renderer spec={view.spec} registry={view.registry} />;
+};
 ```
 
-### Inner boundary — `onRenderError`
+## API Summary
 
-Each catalog element is individually wrapped in a SolidJS `ErrorBoundary` by `@json-render/solid`. When a component throws, it is silently removed while the rest of the spec continues rendering. The outer boundary is **not** triggered.
+### Components
 
-Pass `onRenderError` to `PlayUIProvider` (or `ActorProvider`) — overrides any registry-level handler — or bake it into `defineRegistry`:
+| Export           | Description                                                                    |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `PlayUIProvider` | Batteries-included composite provider (recommended entry point)                |
+| `PlayRenderer`   | Zero-prop leaf component; renders the current view spec inside a provider tree |
+| `ActorProvider`  | Lower-level smart provider for escape-hatch composition                        |
 
-```tsx
-// via PlayUIProvider prop
-<PlayUIProvider
-	actor={actor}
-	registryResult={registryResult}
-	onRenderError={(error, elementType) => {
-		console.warn(`<${elementType}> crashed:`, error);
-	}}
->
-	<PlayRenderer />
-</PlayUIProvider>
-```
+### Hooks
 
-```ts
-// via defineRegistry — bakes the handler into the registry
-const registryResult = defineRegistry(catalog, {
-	components: { Login, Dashboard },
-	actions: { login: async (params) => { ... }, logout: async () => { ... } },
-	onRenderError(error, elementType) {
-		reportExpectedRenderError(error, elementType);
-	},
-});
-```
+| Export          | Description                                                                       |
+| --------------- | --------------------------------------------------------------------------------- |
+| `useActor()`    | Returns the raw `PlayActor` instance from context; throws outside a provider tree |
+| `usePlayView()` | Returns the current `ViewContextValue` (spec, handlers, registry, store)          |
 
-`onRenderError` is typed as `RenderErrorHandler` and exported from.
+### Context
 
----
+| Export         | Description                                                                            |
+| -------------- | -------------------------------------------------------------------------------------- |
+| `ActorContext` | SolidJS context for the actor; use `ActorContext.Provider` directly as an escape hatch |
 
-### `useActor`
+### Re-exports from `@json-render/solid`
 
-Solid hook for accessing the actor from inside any component rendered by `PlayRenderer`. No prop drilling needed.
+This package re-exports the full `@json-render/solid` public API so consumers do not need a direct dependency:
 
 ```tsx
-import { useActor } from "@xmachines/play-solid";
-
-// Inside any component rendered inside PlayRenderer:
-function LogoutButton() {
-	const actor = useActor();
-	return <button onClick={() => actor.send({ type: "auth.logout" })}>Log Out</button>;
-}
+import {
+	// Providers
+	JSONUIProvider,
+	StateProvider,
+	ActionProvider,
+	VisibilityProvider,
+	ValidationProvider,
+	// Renderer
+	Renderer,
+	// Registry factory + hooks
+	defineRegistry,
+	useBoundProp,
+	useStateBinding,
+	useStateValue,
+	useStateStore,
+	useActions,
+	useAction,
+	useIsVisible,
+	useFieldValidation,
+	useOptionalValidation,
+	useVisibility,
+} from "@xmachines/play-solid";
 ```
 
-Throws `NonNullableError: "useActor() must be called inside <ActorProvider> (or <PlayUIProvider>)"` if called outside the tree.
+### Key Types
 
----
+| Type                  | Description                                                           |
+| --------------------- | --------------------------------------------------------------------- |
+| `PlayUIProviderProps` | Props for `PlayUIProvider`                                            |
+| `ActorProviderProps`  | Props for `ActorProvider`                                             |
+| `ViewContextValue`    | Shape of the context value from `usePlayView()`                       |
+| `PlayActor`           | `AbstractActor<AnyActorLogic>` — the actor type accepted by providers |
 
-## Route Parameters in Props
+## Testing
 
-When using `formatPlayRouteTransitions`, URL path parameters flow automatically into component props. Declare an `undefined` slot in the spec to opt in:
+Run tests for this package in isolation:
 
-```ts
-// spec: { section: undefined, user: "alice" }
-// After play.route to /settings/profile → context.params = { section: "profile" }
-// Component receives: { section: "profile", user: "alice" }
+```bash
+npm test -w packages/play-solid
 ```
 
-Priority: **route param fills `undefined` slots; explicit non-`undefined` spec props always win.**
+Or from within the package directory:
 
----
-
-## Architecture Notes
+```bash
+npm test          # single run (jsdom environment)
+npm run test:watch  # watch mode
+npm run test:ui     # interactive Vitest UI
+```
 
-- SolidJS signals are only used to trigger re-renders — not for business logic
-- `actor.currentView` (TC39 Signal) is bridged into a SolidJS `createSignal` inside `PlayRenderer`
-- Per-view UI state lives in an `@xstate/store` atom, not in SolidJS reactive state
-- `@json-render/solid` drives rendering; `PlayRenderer` is the signal bridge — import `defineRegistry`, `ComponentFn`, `ComponentContext`, and `useBoundProp` from
+Coverage is collected with v8 (80% threshold for lines, functions, branches, and statements). Browser-specific tests live in `test/browser/` and are excluded from the default jsdom run.
 
-## Learn More
+## License
 
-- [Demo](examples/demo/README.md)
-- [Solid Router adapter](../play-solid-router/README.md)
-- [TanStack Solid Router adapter](../play-tanstack-solid-router/README.md)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-solid",
-  "version": "1.0.0-beta.46",
+  "version": "1.0.0-beta.47",
   "description": "Solid renderer for XMachines Play architecture",
   "keywords": [
     "catalog",
@@ -39,9 +39,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play": "1.0.0-beta.46",
-    "@xmachines/play-actor": "1.0.0-beta.46",
-    "@xmachines/play-signals": "1.0.0-beta.46"
+    "@xmachines/play": "1.0.0-beta.47",
+    "@xmachines/play-actor": "1.0.0-beta.47",
+    "@xmachines/play-signals": "1.0.0-beta.47"
   },
   "devDependencies": {
     "@json-render/core": "^0.18.0",
@@ -50,7 +50,7 @@
     "@solidjs/testing-library": "^0.8.10",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^25.6.0",
-    "@xmachines/shared": "1.0.0-beta.46",
+    "@xmachines/shared": "1.0.0-beta.47",
     "@xstate/store": "^3.17.0",
     "jsdom": "^29.0.2",
     "oxfmt": "^0.45.0",