@xmachines/play-react 1.0.0-beta.1

package/README.md

@@ -0,0 +1,358 @@
+# @xmachines/play-react
+
+**React renderer consuming signals and UI schema with provider pattern**
+
+Signal-driven React rendering layer observing actor state with zero React state for business logic.
+
+## Overview
+
+`@xmachines/play-react` provides `PlayRenderer` and `useSignalEffect` for building React UIs that passively observe actor signals. This package enables framework-swappable architecture where React is just a rendering target subscribing to signal changes — business logic lives entirely in the actor.
+
+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 useState/useReducer for business logic, signals only
+- **Passive Infrastructure (INV-04):** Components observe signals, send events to actor
+
+**Key Principle:** React state is never used for business logic. Signals are the source of truth.
+
+Renderer receives actor via props (provider pattern), not children.
+
+## Installation
+
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
+npm install @xmachines/play-react
+```
+
+## Current Exports
+
+- `PlayRenderer`
+- `useSignalEffect`
+- `PlayRendererProps` (type)
+
+**Peer dependencies:**
+
+- `react` ^18.0.0 - React runtime
+- `react-dom` ^18.0.0 - React DOM renderer
+
+## Quick Start
+
+```typescript
+import { createRoot } from "react-dom/client";
+import { definePlayer } from "@xmachines/play-xstate";
+import { defineCatalog } from "@xmachines/play-catalog";
+import { PlayRenderer } from "@xmachines/play-react";
+import { z } from "zod";
+
+// 1. Define catalog (business logic layer)
+const catalog = defineCatalog({
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({
+		userId: z.string(),
+		username: z.string(),
+	}),
+});
+
+// 2. Create React components (view layer)
+const components = {
+	LoginForm: ({ error, send }) => (
+		<form
+			onSubmit={(e) => {
+				e.preventDefault();
+				const data = new FormData(e.currentTarget);
+				send({
+					type: "auth.login",
+					username: data.get("username"),
+					password: data.get("password"),
+				});
+			}}
+		>
+			{error && <p style={{ color: "red" }}>{error}</p>}
+			<input name="username" required placeholder="Username" />
+			<input name="password" type="password" required placeholder="Password" />
+			<button type="submit">Log In</button>
+		</form>
+	),
+	Dashboard: ({ userId, username, send }) => (
+		<div>
+			<h1>Welcome, {username}!</h1>
+			<p>User ID: {userId}</p>
+			<button onClick={() => send({ type: "auth.logout" })}>Log Out</button>
+		</div>
+	),
+};
+
+// 3. Create player actor (business logic runtime)
+const createPlayer = definePlayer({ machine: authMachine, catalog });
+const actor = createPlayer();
+actor.start();
+
+// 4. Render UI (actor via props)
+const root = createRoot(document.getElementById("app")!);
+root.render(<PlayRenderer actor={actor} components={components} />);
+```
+
+## API Reference
+
+### PlayRenderer
+
+Main renderer component subscribing to actor signals and dynamically rendering catalog components:
+
+```typescript
+interface PlayRendererProps {
+	actor: AbstractActor<any>;
+	components: Record<string, React.ComponentType<any>>;
+	fallback?: React.ReactNode;
+}
+```
+
+**Props:**
+
+- `actor` - Actor instance with `currentView` signal
+- `components` - Map of component names to React components
+- `fallback` - Component shown when `currentView` is null (default: `null`)
+
+**Behavior:**
+
+1. Subscribes to `actor.currentView` signal via `useSignalEffect`
+2. Looks up component from `components` map using `view.component` string
+3. Renders component with props from `view.props` + `send` function
+
+**Example:**
+
+```typescript
+<PlayRenderer
+	actor={actor}
+	components={{
+		HomePage: ({ send }) => <div>Home</div>,
+		AboutPage: ({ send }) => <div>About</div>,
+	}}
+	fallback={<div>Loading...</div>}
+/>
+```
+
+### useSignalEffect()
+
+Hook for subscribing to signal changes with automatic cleanup:
+
+```typescript
+useSignalEffect(() => {
+	const value = signal.get();
+	// React re-renders when signal changes
+});
+```
+
+**Behavior:**
+
+- Tracks signal dependencies automatically via `Signal.Computed` wrapper
+- Uses `Signal.subtle.Watcher` with microtask batching
+- Triggers React state update to force re-render
+- Cleans up watcher on unmount with explicit `unwatch`
+
+**Canonical watcher lifecycle:**
+
+1. `notify`
+2. `queueMicrotask`
+3. drain pending work (`getPending` and/or `Computed.get`)
+4. run effect + trigger render
+5. re-arm watcher via `watch()`
+
+Watcher notification is one-shot, so re-arm and explicit cleanup are both required.
+
+**Example:**
+
+```typescript
+import { useSignalEffect } from "@xmachines/play-react";
+import { useState } from "react";
+
+function RouteDisplay({ actor }: { actor: AbstractActor<any> }) {
+	const [route, setRoute] = useState<string | null>(null);
+
+	useSignalEffect(() => {
+		const currentRoute = actor.currentRoute.get();
+		setRoute(currentRoute);
+	});
+
+	return <div>Current Route: {route ?? "None"}</div>;
+}
+```
+
+**Complete API:** See [API Documentation](../../docs/api/@xmachines/play-react)
+
+## Examples
+
+### Component Receiving Props from Catalog
+
+```typescript
+import { PlayRenderer } from "@xmachines/play-react";
+import { defineCatalog } from "@xmachines/play-catalog";
+import { z } from "zod";
+
+// Define schema in catalog
+const catalog = defineCatalog({
+	UserProfile: z.object({
+		userId: z.string(),
+		name: z.string(),
+		avatar: z.string().url().optional(),
+		stats: z.object({
+			posts: z.number(),
+			followers: z.number(),
+		}),
+	}),
+});
+
+// Component receives type-safe props + send
+const components = {
+	UserProfile: ({ userId, name, avatar, stats, send }) => (
+		<div>
+			{avatar && <img src={avatar} alt={name} />}
+			<h1>{name}</h1>
+			<p>ID: {userId}</p>
+			<div>
+				<span>{stats.posts} posts</span>
+				<span>{stats.followers} followers</span>
+			</div>
+			<button
+				onClick={() =>
+					send({
+						type: "profile.edit",
+						userId,
+					})
+				}
+			>
+				Edit Profile
+			</button>
+		</div>
+	),
+};
+
+<PlayRenderer actor={actor} components={components} />;
+```
+
+### useSignalEffect for Custom Rendering
+
+```typescript
+import { useSignalEffect } from "@xmachines/play-react";
+import { AbstractActor } from "@xmachines/play-actor";
+
+function CustomRenderer({ actor }: { actor: AbstractActor<any> }) {
+	const [view, setView] = useState(null);
+
+	// Subscribe to currentView signal
+	useSignalEffect(() => {
+		const currentView = actor.currentView.get();
+		setView(currentView);
+	});
+
+	if (!view) return <div>No view</div>;
+
+	// Custom rendering logic
+	if (view.component === "SpecialCase") {
+		return <SpecialCaseComponent {...view.props} actor={actor} />;
+	}
+
+	// Fallback to standard rendering
+	return <DefaultComponent view={view} actor={actor} />;
+}
+```
+
+### Provider Pattern
+
+```typescript
+import { PlayTanStackRouterProvider } from "@xmachines/play-tanstack-react-router";
+import { PlayRenderer } from "@xmachines/play-react";
+
+// Renderer receives actor via props (not children)
+function App() {
+	return (
+		<PlayTanStackRouterProvider
+			actor={actor}
+			router={router}
+			renderer={(currentActor, currentRouter) => {
+				void currentRouter;
+				return (
+				<div>
+					<Header actor={currentActor} />
+					<PlayRenderer actor={currentActor} components={components} />
+					<Footer />
+				</div>
+				);
+			}}
+		/>
+	);
+}
+
+// Header component also receives actor
+function Header({ actor }: { actor: AbstractActor<any> }) {
+	const [route, setRoute] = useState<string | null>(null);
+
+	useSignalEffect(() => {
+		setRoute(actor.currentRoute.get());
+	});
+
+	return (
+		<header>
+			<nav>Current: {route}</nav>
+		</header>
+	);
+}
+```
+
+## Architecture
+
+This package implements **Signal-Only Reactivity (INV-05)** and **Passive Infrastructure (INV-04)**:
+
+1. **No Business Logic in React:**
+    - No useState/useReducer for business state
+    - No useEffect for side effects
+    - React only triggers renders, doesn't control state
+
+2. **Signals as Source of Truth:**
+    - `actor.currentView.get()` provides UI structure
+    - `actor.currentRoute.get()` provides navigation state
+    - Components observe signals via `useSignalEffect`
+
+3. **Event Forwarding:**
+    - Components receive `send` function via props
+    - User actions send events to actor (e.g., `{ type: "auth.login" }`)
+    - Actor guards validate and process events
+
+4. **Microtask Batching:**
+    - `Signal.subtle.Watcher` coalesces rapid signal changes
+    - Prevents React thrashing from multiple signal updates
+    - Single React render per microtask batch
+
+5. **Explicit Disposal Contract:**
+    - Component teardown must call watcher `unwatch` in cleanup
+    - Do not rely on GC-only cleanup
+
+**Pattern:**
+
+- Renderer receives actor via props (provider pattern)
+- Enables composition with navigation, headers, footers
+- Supports multiple renderers in same app
+
+**Architectural Invariants:**
+
+- **Signal-Only Reactivity (INV-05):** No React state for business logic
+- **Passive Infrastructure (INV-04):** Components reflect, never decide
+
+## Benefits
+
+- **Framework Swappable:** Business logic has zero React imports
+- **Type Safety:** Props validated against catalog schemas
+- **Simple Testing:** Test actors without React renderer
+- **Performance:** Microtask batching reduces unnecessary renders
+- **Composability:** Renderer prop enables complex layouts ()
+
+## Related Packages
+
+- **[@xmachines/play-xstate](../play-xstate)** - XState adapter providing actors
+- **[@xmachines/play-catalog](../play-catalog)** - UI schema validation
+- **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router)** - TanStack Router integration
+- **[@xmachines/play-actor](../play-actor)** - Actor base
+- **[@xmachines/play-signals](../play-signals)** - TC39 Signals primitives
+
+## License
+
+MIT

package/dist/PlayRenderer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * PlayRenderer - Main React renderer component for XMachines Play architecture
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+import type { PlayRendererProps } from "./types.js";
+/**
+ * Main renderer component that subscribes to actor signals and renders UI
+ *
+ * Architecture (per RESEARCH.md Pattern 1):
+ * - Subscribes to actor.currentView signal via useSignalEffect
+ * - Dynamically renders catalog components based on view.component string
+ * - Forwards user events to actor via actor.send()
+ * - React state only for triggering renders, NOT business logic
+ *
+ * Invariant: Actor Authority - Actor decides all state transitions via guards.
+ * Invariant: Passive Infrastructure - Component observes signals and sends events.
+ * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
+ *
+ * @example
+ * ```typescript
+ * import { PlayRenderer } from "@xmachines/play-react";
+ * import { definePlayer } from "@xmachines/play-xstate";
+ *
+ * const actor = definePlayer({ machine, catalog })();
+ * actor.start();
+ *
+ * const components = {
+ *   Dashboard: ({ userId, send }) => <div>User: {userId}</div>,
+ *   LoginForm: ({ error, send }) => <form onSubmit={(e) => {
+ *     e.preventDefault();
+ *     send({ type: "intent", name: "login.submit", payload: {...} });
+ *   }}>...</form>
+ * };
+ *
+ * <PlayRenderer actor={actor} components={components} />
+ * ```
+ *
+ * @param props - Component props
+ * @returns React element rendering current view from actor
+ *
+ * @remarks
+ * **Component lookup:** Dynamically looks up component from `components` map
+ * using `view.component` string from actor.currentView signal.
+ *
+ * **Event forwarding:** Injects `send` function as prop to components. Components
+ * call `send(event)` to forward intents to actor. Actor guards decide validity.
+ *
+ * **Error handling:** If component not found in catalog, logs error and shows
+ * fallback. This indicates missing component registration, not runtime error.
+ *
+ * **CRITICAL:** Never call actor.send() during render - only in event handlers.
+ * Calling send during render causes infinite render loops.
+ */
+export declare const PlayRenderer: React.FC<PlayRendererProps>;
+//# sourceMappingURL=PlayRenderer.d.ts.map

package/dist/PlayRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAmB,MAAM,OAAO,CAAC;AAExC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA2CpD,CAAC"}

package/dist/PlayRenderer.js

@@ -0,0 +1,87 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * PlayRenderer - Main React renderer component for XMachines Play architecture
+ *
+ * @packageDocumentation
+ */
+import React, { useState } from "react";
+import { useSignalEffect } from "./useSignalEffect.js";
+/**
+ * Main renderer component that subscribes to actor signals and renders UI
+ *
+ * Architecture (per RESEARCH.md Pattern 1):
+ * - Subscribes to actor.currentView signal via useSignalEffect
+ * - Dynamically renders catalog components based on view.component string
+ * - Forwards user events to actor via actor.send()
+ * - React state only for triggering renders, NOT business logic
+ *
+ * Invariant: Actor Authority - Actor decides all state transitions via guards.
+ * Invariant: Passive Infrastructure - Component observes signals and sends events.
+ * Invariant: Signal-Only Reactivity - Business logic state lives in actor signals.
+ *
+ * @example
+ * ```typescript
+ * import { PlayRenderer } from "@xmachines/play-react";
+ * import { definePlayer } from "@xmachines/play-xstate";
+ *
+ * const actor = definePlayer({ machine, catalog })();
+ * actor.start();
+ *
+ * const components = {
+ *   Dashboard: ({ userId, send }) => <div>User: {userId}</div>,
+ *   LoginForm: ({ error, send }) => <form onSubmit={(e) => {
+ *     e.preventDefault();
+ *     send({ type: "intent", name: "login.submit", payload: {...} });
+ *   }}>...</form>
+ * };
+ *
+ * <PlayRenderer actor={actor} components={components} />
+ * ```
+ *
+ * @param props - Component props
+ * @returns React element rendering current view from actor
+ *
+ * @remarks
+ * **Component lookup:** Dynamically looks up component from `components` map
+ * using `view.component` string from actor.currentView signal.
+ *
+ * **Event forwarding:** Injects `send` function as prop to components. Components
+ * call `send(event)` to forward intents to actor. Actor guards decide validity.
+ *
+ * **Error handling:** If component not found in catalog, logs error and shows
+ * fallback. This indicates missing component registration, not runtime error.
+ *
+ * **CRITICAL:** Never call actor.send() during render - only in event handlers.
+ * Calling send during render causes infinite render loops.
+ */
+export const PlayRenderer = ({ actor, components, fallback = null, }) => {
+    // React state for triggering re-renders (NOT business logic state)
+    // Signal is source of truth, useState is just React's render trigger
+    const [view, setView] = useState(() => actor.currentView.get());
+    // Subscribe to signal changes
+    useSignalEffect(() => {
+        const currentView = actor.currentView.get();
+        setView(currentView);
+    });
+    // No view in current state
+    if (!view) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    // Handle null/undefined components catalog gracefully
+    if (!components) {
+        console.error(`Components catalog is ${components === null ? "null" : "undefined"}. ` +
+            `Cannot render component "${view.component}".`);
+        return _jsx(_Fragment, { children: fallback });
+    }
+    // Look up component from catalog
+    const Component = components[view.component];
+    if (!Component) {
+        console.error(`Component "${view.component}" not found in catalog. ` +
+            `Available components: ${Object.keys(components).join(", ")}`);
+        return _jsx(_Fragment, { children: fallback });
+    }
+    // Render with props from actor + send function
+    // bind(actor) ensures 'this' context is correct when components call send()
+    return _jsx(Component, { ...view.props, send: actor.send.bind(actor) });
+};
+//# sourceMappingURL=PlayRenderer.js.map

package/dist/PlayRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.tsx"],"names":[],"mappings":";AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgC,CAAC,EACzD,KAAK,EACL,UAAU,EACV,QAAQ,GAAG,IAAI,GACf,EAAE,EAAE;IACJ,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;IAEhE,8BAA8B;IAC9B,eAAe,CAAC,GAAG,EAAE;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QAC5C,OAAO,CAAC,WAAW,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,2BAA2B;IAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,sDAAsD;IACtD,IAAI,CAAC,UAAU,EAAE,CAAC;QACjB,OAAO,CAAC,KAAK,CACZ,yBAAyB,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI;YACtE,4BAA4B,IAAI,CAAC,SAAS,IAAI,CAC/C,CAAC;QACF,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,iCAAiC;IACjC,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE7C,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACZ,cAAc,IAAI,CAAC,SAAS,0BAA0B;YACrD,yBAAyB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9D,CAAC;QACF,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACxB,CAAC;IAED,+CAA+C;IAC/C,4EAA4E;IAC5E,OAAO,KAAC,SAAS,OAAK,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAI,CAAC;AACpE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @xmachines/play-react - React renderer for XMachines Play architecture
+ *
+ * Provides a thin React rendering layer that passively observes actor signals
+ * and renders UI components from catalog definitions. This package enables
+ * framework-swappable architecture where React is just a rendering target
+ * that subscribes to signal changes.
+ *
+ * **Key principle:** React state is NEVER used for business logic—only for
+ * triggering React's render cycle. Signals are the source of truth.
+ *
+ * @packageDocumentation
+ * @module @xmachines/play-react
+ */
+export { PlayRenderer } from "./PlayRenderer.js";
+export { useSignalEffect } from "./useSignalEffect.js";
+export type { PlayRendererProps } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @xmachines/play-react - React renderer for XMachines Play architecture
+ *
+ * Provides a thin React rendering layer that passively observes actor signals
+ * and renders UI components from catalog definitions. This package enables
+ * framework-swappable architecture where React is just a rendering target
+ * that subscribes to signal changes.
+ *
+ * **Key principle:** React state is NEVER used for business logic—only for
+ * triggering React's render cycle. Signals are the source of truth.
+ *
+ * @packageDocumentation
+ * @module @xmachines/play-react
+ */
+// Main exports
+export { PlayRenderer } from "./PlayRenderer.js";
+export { useSignalEffect } from "./useSignalEffect.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TypeScript type definitions for play-react
+ *
+ * @packageDocumentation
+ */
+import type { AbstractActor, Viewable } from "@xmachines/play-actor";
+import type React from "react";
+import type { AnyActorLogic } from "xstate";
+/**
+ * Props for PlayRenderer component
+ *
+ * @property actor - Actor instance with currentView signal (requires Viewable capability)
+ * @property components - Map of component names to React components
+ * @property fallback - Optional component shown when currentView is null
+ */
+export interface PlayRendererProps {
+    /** Actor instance with currentView signal (requires Viewable capability) */
+    actor: AbstractActor<AnyActorLogic> & Viewable;
+    /** Map of component names to React components */
+    components: Record<string, React.ElementType>;
+    /** Optional component shown when currentView is null */
+    fallback?: React.ReactNode;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAE/C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAE9C,wDAAwD;IACxD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * TypeScript type definitions for play-react
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/useSignalEffect.d.ts

@@ -0,0 +1,56 @@
+/**
+ * useSignalEffect - React hook for signal subscriptions with automatic cleanup
+ *
+ * @packageDocumentation
+ */
+/**
+ * React hook that subscribes to signal changes and runs effect callback
+ *
+ * Wraps Signal.subtle.Watcher to automatically track signal dependencies
+ * accessed in the callback. When any tracked signal changes, the callback
+ * re-runs and React component re-renders.
+ *
+ * Architecture (per RESEARCH.md Pattern 3):
+ * - Uses Signal.Computed to wrap callback for automatic dependency tracking
+ * - Signal.subtle.Watcher monitors the Computed for changes
+ * - Microtask batching coalesces rapid signal updates
+ * - Forces React re-render via useReducer when signals change
+ * - Handles cleanup on unmount to prevent memory leaks
+ *
+ * Invariant: Signal-Only Reactivity - Signals accessed in callback are watched.
+ * Invariant: Passive Infrastructure - React observes signals and does not control them.
+ *
+ * @param callback - Effect function that accesses signals. Can return cleanup function.
+ *
+ * @example
+ * ```typescript
+ * const MyComponent = ({ actor }) => {
+ *   const [view, setView] = useState(null);
+ *
+ *   // Subscribe to actor.currentView signal
+ *   useSignalEffect(() => {
+ *     const currentView = actor.currentView.get();
+ *     setView(currentView);
+ *   });
+ *
+ *   return <div>{view?.component}</div>;
+ * };
+ * ```
+ *
+ * @remarks
+ * **CRITICAL:** Signals must be accessed unconditionally (no if statements).
+ * Conditional signal access breaks automatic dependency tracking.
+ *
+ * **Performance:** Microtask batching (queueMicrotask) prevents React thrashing
+ * when multiple signals update rapidly. Per signal-polyfill README pattern.
+ *
+ * **Why forceUpdate:** React needs useState/useReducer to trigger re-render cycle.
+ * Signal changes won't automatically re-render React components without forcing
+ * update via state change.
+ *
+ * **Implementation note:** We wrap the callback in Signal.Computed because
+ * Signal.subtle.Watcher cannot automatically track arbitrary function calls.
+ * The Computed handles dependency tracking, and the Watcher monitors it.
+ */
+export declare const useSignalEffect: (callback: () => void | (() => void)) => void;
+//# sourceMappingURL=useSignalEffect.d.ts.map

package/dist/useSignalEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSignalEffect.d.ts","sourceRoot":"","sources":["../src/useSignalEffect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,KAAG,IAuDrE,CAAC"}

package/dist/useSignalEffect.js

@@ -0,0 +1,107 @@
+/**
+ * useSignalEffect - React hook for signal subscriptions with automatic cleanup
+ *
+ * @packageDocumentation
+ */
+import { useEffect, useReducer } from "react";
+import { Signal } from "@xmachines/play-signals";
+/**
+ * Marker symbol returned by effect Computed to satisfy type requirements
+ * The actual value doesn't matter - we only care about side effects
+ */
+const EFFECT_RUN_MARKER = Symbol("effect-run");
+/**
+ * React hook that subscribes to signal changes and runs effect callback
+ *
+ * Wraps Signal.subtle.Watcher to automatically track signal dependencies
+ * accessed in the callback. When any tracked signal changes, the callback
+ * re-runs and React component re-renders.
+ *
+ * Architecture (per RESEARCH.md Pattern 3):
+ * - Uses Signal.Computed to wrap callback for automatic dependency tracking
+ * - Signal.subtle.Watcher monitors the Computed for changes
+ * - Microtask batching coalesces rapid signal updates
+ * - Forces React re-render via useReducer when signals change
+ * - Handles cleanup on unmount to prevent memory leaks
+ *
+ * Invariant: Signal-Only Reactivity - Signals accessed in callback are watched.
+ * Invariant: Passive Infrastructure - React observes signals and does not control them.
+ *
+ * @param callback - Effect function that accesses signals. Can return cleanup function.
+ *
+ * @example
+ * ```typescript
+ * const MyComponent = ({ actor }) => {
+ *   const [view, setView] = useState(null);
+ *
+ *   // Subscribe to actor.currentView signal
+ *   useSignalEffect(() => {
+ *     const currentView = actor.currentView.get();
+ *     setView(currentView);
+ *   });
+ *
+ *   return <div>{view?.component}</div>;
+ * };
+ * ```
+ *
+ * @remarks
+ * **CRITICAL:** Signals must be accessed unconditionally (no if statements).
+ * Conditional signal access breaks automatic dependency tracking.
+ *
+ * **Performance:** Microtask batching (queueMicrotask) prevents React thrashing
+ * when multiple signals update rapidly. Per signal-polyfill README pattern.
+ *
+ * **Why forceUpdate:** React needs useState/useReducer to trigger re-render cycle.
+ * Signal changes won't automatically re-render React components without forcing
+ * update via state change.
+ *
+ * **Implementation note:** We wrap the callback in Signal.Computed because
+ * Signal.subtle.Watcher cannot automatically track arbitrary function calls.
+ * The Computed handles dependency tracking, and the Watcher monitors it.
+ */
+export const useSignalEffect = (callback) => {
+    // Force re-render when signal changes (React needs state change to re-render)
+    const [, forceUpdate] = useReducer((x) => x + 1, 0);
+    useEffect(() => {
+        let cleanup;
+        let needsEnqueue = true;
+        // Wrap callback in a Computed to automatically track dependencies
+        // The Computed will re-evaluate when any accessed signal changes
+        const effect = new Signal.Computed(() => {
+            // Run cleanup from previous effect
+            cleanup?.();
+            // Run user callback (may access signals, return cleanup)
+            cleanup = callback();
+            // Return marker value (Computed requires a return value)
+            return EFFECT_RUN_MARKER;
+        });
+        // Create watcher to detect when Computed needs re-evaluation
+        const watcher = new Signal.subtle.Watcher(() => {
+            // Batching flag prevents multiple microtasks for rapid changes
+            if (needsEnqueue) {
+                needsEnqueue = false;
+                // Schedule microtask to batch updates (prevent React thrashing)
+                queueMicrotask(() => {
+                    needsEnqueue = true;
+                    // Re-evaluate the Computed (runs callback with new signal values)
+                    effect.get();
+                    // Force React re-render
+                    forceUpdate();
+                    // Re-watch for next change
+                    watcher.watch();
+                });
+            }
+        });
+        // Watch the Computed signal
+        watcher.watch(effect);
+        // Initial run of callback (via Computed)
+        effect.get();
+        // Cleanup on unmount
+        return () => {
+            cleanup?.();
+            // Unwatch to stop receiving signal updates
+            watcher.unwatch(effect);
+        };
+    }, [callback]);
+};
+//# sourceMappingURL=useSignalEffect.js.map

package/dist/useSignalEffect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSignalEffect.js","sourceRoot":"","sources":["../src/useSignalEffect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD;;;GAGG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAmC,EAAQ,EAAE;IAC5E,8EAA8E;IAC9E,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpD,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAA4B,CAAC;QACjC,IAAI,YAAY,GAAG,IAAI,CAAC;QAExB,kEAAkE;QAClE,iEAAiE;QACjE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE;YACvC,mCAAmC;YACnC,OAAO,EAAE,EAAE,CAAC;YAEZ,yDAAyD;YACzD,OAAO,GAAG,QAAQ,EAAE,CAAC;YAErB,yDAAyD;YACzD,OAAO,iBAAiB,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,6DAA6D;QAC7D,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;YAC9C,+DAA+D;YAC/D,IAAI,YAAY,EAAE,CAAC;gBAClB,YAAY,GAAG,KAAK,CAAC;gBACrB,gEAAgE;gBAChE,cAAc,CAAC,GAAG,EAAE;oBACnB,YAAY,GAAG,IAAI,CAAC;oBAEpB,kEAAkE;oBAClE,MAAM,CAAC,GAAG,EAAE,CAAC;oBAEb,wBAAwB;oBACxB,WAAW,EAAE,CAAC;oBAEd,2BAA2B;oBAC3B,OAAO,CAAC,KAAK,EAAE,CAAC;gBACjB,CAAC,CAAC,CAAC;YACJ,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,4BAA4B;QAC5B,OAAO,CAAC,KAAK,CAAC,MAAa,CAAC,CAAC;QAE7B,yCAAyC;QACzC,MAAM,CAAC,GAAG,EAAE,CAAC;QAEb,qBAAqB;QACrB,OAAO,GAAG,EAAE;YACX,OAAO,EAAE,EAAE,CAAC;YACZ,2CAA2C;YAC3C,OAAO,CAAC,OAAO,CAAC,MAAa,CAAC,CAAC;QAChC,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@xmachines/play-react",
+  "version": "1.0.0-beta.1",
+  "description": "React renderer for XMachines Play architecture with signal-driven rendering",
+  "keywords": [
+    "actor",
+    "react",
+    "renderer",
+    "signals",
+    "state-machine",
+    "ui",
+    "xmachines"
+  ],
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:xmachin-es/xmachines-js.git",
+    "directory": "packages/play-react"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:vitest": "vitest run",
+    "test:browser": "vitest run --browser.enabled --browser.name=chromium test/browser",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@xmachines/play-actor": "1.0.0-beta.1",
+    "@xmachines/play-catalog": "1.0.0-beta.1",
+    "@xmachines/play-signals": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^25.4.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^28.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}