@xmachines/play-solid 1.0.0-beta.6 → 1.0.0-beta.8

package/README.md

@@ -1,11 +1,27 @@
 # @xmachines/play-solid
 
-SolidJS renderer for XMachines Play architecture. Enables catalog-driven view rendering with actor-owned business state.
+**SolidJS renderer consuming signals and UI schema with provider pattern**
+
+Signal-driven SolidJS rendering layer observing actor state with zero SolidJS state for business logic.
+
+## Overview
+
+`@xmachines/play-solid` provides `PlayRenderer` for building SolidJS UIs that passively observe actor signals. This package enables framework-swappable architecture where SolidJS is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
+
+Per [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md), this package implements:
+
+- **Signal-Only Reactivity (INV-05):** No createSignal/createStore for business logic, TC39 signals only
+- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
+
+**Key Principle:** SolidJS state is never used for business logic. Signals are the source of truth.
+
+Renderer receives actor via props (provider pattern), not children.
 
 ## Installation
 
 ```bash
-npm install @xmachines/play-solid solid-js
+npm install solid-js@^1.8.0
+npm install @xmachines/play-solid
 ```
 
 ## Current Exports
@@ -13,98 +29,271 @@ npm install @xmachines/play-solid solid-js
 - `PlayRenderer`
 - `PlayRendererProps` (type)
 
-## Usage
+**Peer dependencies:**
 
-```typescript
-import { PlayRenderer } from '@xmachines/play-solid';
-import { definePlayer } from '@xmachines/play-xstate';
-import { defineCatalog } from '@xmachines/play-catalog';
+- `solid-js` ^1.8.0 - SolidJS runtime
+
+## Quick Start
 
-// Define catalog
+```tsx
+import { render } from "solid-js/web";
+import { definePlayer } from "@xmachines/play-xstate";
+import { defineCatalog } from "@xmachines/play-catalog";
+import { PlayRenderer } from "@xmachines/play-solid";
+import { z } from "zod";
+
+// 1. Define catalog (business logic layer)
 const catalog = defineCatalog({
-  Home: { component: 'Home', props: {} },
-  Login: { component: 'Login', props: { error: { type: 'string' } } }
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({
+		userId: z.string(),
+		username: z.string(),
+	}),
 });
 
-// Create player
-const createPlayer = definePlayer({
-  machine: authMachine,
-  catalog
-});
+// 2. Create SolidJS components (view layer)
+const components = {
+	LoginForm: (props) => (
+		<form
+			onSubmit={(e) => {
+				e.preventDefault();
+				const data = new FormData(e.currentTarget);
+				props.send({
+					type: "auth.login",
+					username: data.get("username"),
+				});
+			}}
+		>
+			{props.error && <p style={{ color: "red" }}>{props.error}</p>}
+			<input name="username" required placeholder="Username" />
+			<button type="submit">Log In</button>
+		</form>
+	),
+	Dashboard: (props) => (
+		<div>
+			<h1>Welcome, {props.username}!</h1>
+			<p>User ID: {props.userId}</p>
+			<button onClick={() => props.send({ type: "auth.logout" })}>Log Out</button>
+		</div>
+	),
+};
 
+// 3. Create player actor (business logic runtime)
+const createPlayer = definePlayer({ machine: authMachine, catalog });
 const actor = createPlayer();
 actor.start();
 
-// Define components
-const components = {
-  Home: (props) => <div>Home</div>,
-  Login: (props) => (
-    <form onSubmit={(e) => {
-      e.preventDefault();
-      props.send({ type: 'auth.login', payload: {...} });
-    }}>
-      {props.error && <p>{props.error}</p>}
-      <input type="text" name="username" />
-      <button type="submit">Login</button>
-    </form>
-  )
-};
-
-// Render
-<PlayRenderer actor={actor} components={components} />
+// 4. Render UI (actor via props)
+render(
+	() => <PlayRenderer actor={actor} components={components} />,
+	document.getElementById("app")!,
+);
 ```
 
-## API
+## API Reference
 
 ### PlayRenderer
 
-Component that observes `actor.currentView` signal and renders the appropriate component from the catalog.
+Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+
+```typescript
+interface PlayRendererProps {
+	actor: AbstractActor<any>;
+	components: Record<string, Component<any>>;
+	fallback?: JSX.Element;
+}
+```
 
 **Props:**
 
-- `actor: AbstractActor & Viewable` - Actor instance with currentView signal
-- `components: Record<string, Component<any>>` - Map of component names to SolidJS components
-- `fallback?: JSX.Element` - Optional fallback to show when currentView is null
+- `actor` - Actor instance with `currentView` signal
+- `components` - Map of component names to SolidJS components
+- `fallback` - Component shown when `currentView` is null
 
-**Features:**
+**Behavior:**
 
-- Automatically bridges TC39 Signals to SolidJS reactivity
-- Passes `send` function to components for event forwarding
-- Handles missing components gracefully with error logging
-- Uses one-shot watcher re-watch pattern for proper signal observation
+1. Subscribes to `actor.currentView` signal using a `Signal.subtle.Watcher` inside the component
+2. Looks up component from `components` map using `view.component` string
+3. Renders component with props from `view.props` + `send` function using Solid's `<Dynamic />`
 
-## Canonical Watcher Lifecycle
+**Example:**
 
-Use the same watcher flow as React/Vue/router packages:
+```tsx
+<PlayRenderer
+	actor={actor}
+	components={{
+		HomePage: (props) => <div>Home</div>,
+		AboutPage: (props) => <div>About</div>,
+	}}
+	fallback={<div>Loading...</div>}
+/>
+```
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. read actor signals and update framework-local render trigger
-5. re-arm with `watch(...)` or `watch()`
+## Examples
 
-Watcher notifications are one-shot, so re-arm is mandatory.
+### Component Receiving Props from Catalog
 
-## Cleanup Contract
+```tsx
+import { PlayRenderer } from "@xmachines/play-solid";
+import { defineCatalog } from "@xmachines/play-catalog";
+import { z } from "zod";
 
-Solid integrations must perform explicit teardown:
+// 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(),
+		}),
+	}),
+});
 
-- Use `onCleanup` for lifecycle teardown.
-- Call `unwatch(...)` on teardown, not only reference nulling.
-- Keep adapters/renderers passive; state validity remains actor-owned.
+// Component receives type-safe props + send
+const components = {
+	UserProfile: (props) => (
+		<div>
+			{props.avatar && <img src={props.avatar} alt={props.name} />}
+			<h1>{props.name}</h1>
+			<p>ID: {props.userId}</p>
+			<div>
+				<span>{props.stats.posts} posts</span>
+				<span>{props.stats.followers} followers</span>
+			</div>
+			<button
+				onClick={() =>
+					props.send({
+						type: "profile.edit",
+						userId: props.userId,
+					})
+				}
+			>
+				Edit Profile
+			</button>
+		</div>
+	),
+};
+
+<PlayRenderer actor={actor} components={components} />;
+```
+
+### Provider Pattern
+
+```tsx
+import { PlayTanStackRouterProvider } from "@xmachines/play-tanstack-solid-router";
+import { PlayRenderer } from "@xmachines/play-solid";
+import { createSignal, onCleanup } from "solid-js";
+
+// Renderer receives actor via props (not children)
+function App() {
+	return (
+		<PlayTanStackRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => {
+				return (
+					<div>
+						<Header actor={currentActor} />
+						<PlayRenderer actor={currentActor} components={components} />
+						<Footer />
+					</div>
+				);
+			}}
+		/>
+	);
+}
+
+// Header component also receives actor
+function Header(props) {
+	const [route, setRoute] = createSignal<string | null>(null);
+
+	// Manual watcher setup for custom component reading signals
+	let watcher: Signal.subtle.Watcher;
+
+	// ... setup watcher to update route signal ...
+
+	return (
+		<header>
+			<nav>Current: {route()}</nav>
+		</header>
+	);
+}
+```
 
 ## Architecture
 
-PlayRenderer follows the XMachines Play architecture:
+This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+
+1. **No Business Logic in SolidJS:**
+    - No createSignal/createStore for business state
+    - No createEffect for business side effects
+    - SolidJS only triggers renders, doesn't control state
+
+2. **Signals as Source of Truth:**
+    - `actor.currentView.get()` provides UI structure
+    - `actor.currentRoute.get()` provides navigation state
+    - Components observe signals via explicit watcher patterns
+
+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 SolidJS thrashing from multiple signal updates
+    - Single SolidJS render per microtask batch
+
+5. **Explicit Disposal Contract:**
+    - Component teardown calls watcher `unwatch` in `onCleanup`
+    - Do not rely on GC-only cleanup
 
-- **Actor Authority**: Actor controls all state transitions via guards
-- **Passive Infrastructure**: Renderer observes signals, sends events
-- **Signal-Only Reactivity**: Business logic state lives in actor signals
+**Pattern:**
 
-The renderer bridges TC39 Signals (used by XMachines actors) to SolidJS's reactivity system using `Signal.subtle.Watcher` with a one-shot re-watch pattern.
+- Renderer receives actor via props (provider pattern)
+- Enables composition with navigation, headers, footers
+- Supports multiple renderers in same app
 
-Signals remain observation plumbing, not an alternate mutation channel.
+**Architectural Invariants:**
+
+- **Signal-Only Reactivity (INV-05):** No SolidJS state for business logic
+- **Passive Infrastructure (INV-04):** Components reflect, never decide
+
+## Canonical Watcher Lifecycle
+
+If you write your own custom integration, use the same watcher flow as `PlayRenderer`:
+
+1. `notify` callback runs
+2. Schedule work with `queueMicrotask`
+3. Drain `watcher.getPending()`
+4. Read actor signals and update SolidJS-local signal state (`setSignal()`)
+5. Re-arm with `watch(...)` or `watch()`
+
+Watcher notify is one-shot. Re-arm is required for continuous observation.
+
+## Benefits
+
+- **Framework Swappable:** Business logic has zero SolidJS imports
+- **Type Safety:** Props validated against catalog schemas
+- **Simple Testing:** Test actors without SolidJS renderer
+- **Performance:** Microtask batching reduces unnecessary renders
+- **Composability:** Renderer prop enables complex layouts
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate)** - XState adapter providing actors
+- **[@xmachines/play-catalog](../play-catalog)** - UI schema validation
+- **[@xmachines/play-solid-router](../play-solid-router)** - Solid Router integration
+- **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router)** - TanStack Solid Router integration
+- **[@xmachines/play-actor](../play-actor)** - Actor base
+- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
 
 ## License
 
-MIT
+Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
+
+This work is licensed under the terms of the MIT license.  
+For a copy, see <https://opensource.org/licenses/MIT>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-solid",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "description": "SolidJS renderer for XMachines Play architecture",
   "keywords": [
     "catalog",
@@ -29,22 +29,22 @@
   },
   "scripts": {
     "build": "vite build && tsc --build",
-    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play-actor": "1.0.0-beta.6",
-    "@xmachines/play-catalog": "1.0.0-beta.6",
-    "@xmachines/play-signals": "1.0.0-beta.6"
+    "@xmachines/play-actor": "1.0.0-beta.8",
+    "@xmachines/play-catalog": "1.0.0-beta.8",
+    "@xmachines/play-signals": "1.0.0-beta.8"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10",
     "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.6",
+    "@xmachines/shared": "1.0.0-beta.8",
     "solid-js": "^1.9.11",
     "typescript": "^5.9.3",
     "vite": "^8.0.0",