@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md

@@ -0,0 +1,85 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / Watcher
+
+# Class: Watcher
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:29
+
+## Constructors
+
+### Constructor
+
+```ts
+new Watcher(notify): Watcher;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:32
+
+#### Parameters
+
+| Parameter | Type               |
+| --------- | ------------------ |
+| `notify`  | (`this`) => `void` |
+
+#### Returns
+
+`Watcher`
+
+## Properties
+
+| Property                            | Modifier   | Type           | Defined in                                        |
+| ----------------------------------- | ---------- | -------------- | ------------------------------------------------- |
+| <a id="property-node"></a> `[NODE]` | `readonly` | `ReactiveNode` | node_modules/signal-polyfill/dist/wrapper.d.ts:31 |
+
+## Methods
+
+### getPending()
+
+```ts
+getPending(): Computed<any>[];
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:35
+
+#### Returns
+
+[`Computed`](../../../classes/Computed.md)\<`any`\>[]
+
+---
+
+### unwatch()
+
+```ts
+unwatch(...signals): void;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:34
+
+#### Parameters
+
+| Parameter    | Type                   |
+| ------------ | ---------------------- |
+| ...`signals` | `AnySignal`\<`any`\>[] |
+
+#### Returns
+
+`void`
+
+---
+
+### watch()
+
+```ts
+watch(...signals): void;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:33
+
+#### Parameters
+
+| Parameter    | Type                   |
+| ------------ | ---------------------- |
+| ...`signals` | `AnySignal`\<`any`\>[] |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/functions/currentComputed.md

@@ -0,0 +1,13 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / currentComputed
+
+# Function: currentComputed()
+
+```ts
+function currentComputed(): Computed<any> | undefined;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:37
+
+## Returns
+
+[`Computed`](../../../classes/Computed.md)\<`any`\> \| `undefined`

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/functions/hasSinks.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / hasSinks
+
+# Function: hasSinks()
+
+```ts
+function hasSinks(signal): boolean;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:27
+
+## Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `signal`  | `AnySignal` |
+
+## Returns
+
+`boolean`

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/functions/hasSources.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / hasSources
+
+# Function: hasSources()
+
+```ts
+function hasSources(signal): boolean;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:28
+
+## Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `signal`  | `AnySink` |
+
+## Returns
+
+`boolean`

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/functions/introspectSinks.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / introspectSinks
+
+# Function: introspectSinks()
+
+```ts
+function introspectSinks(signal): AnySink[];
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:26
+
+## Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `signal`  | `AnySignal` |
+
+## Returns
+
+`AnySink`[]

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/functions/introspectSources.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / introspectSources
+
+# Function: introspectSources()
+
+```ts
+function introspectSources(sink): AnySignal<any>[];
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:25
+
+## Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `sink`    | `AnySink` |
+
+## Returns
+
+`AnySignal`\<`any`\>[]

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/functions/untrack.md

@@ -0,0 +1,25 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / untrack
+
+# Function: untrack()
+
+```ts
+function untrack<T>(cb): T;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:24
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `cb`      | () => `T` |
+
+## Returns
+
+`T`

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/variables/unwatched.md

@@ -0,0 +1,9 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / unwatched
+
+# Variable: unwatched
+
+```ts
+const unwatched: unique symbol;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:39

package/api/@xmachines/play-signals/namespaces/Signal/namespaces/subtle/variables/watched.md

@@ -0,0 +1,9 @@
+[Documentation](../../../../../../../README.md) / [@xmachines/play-signals](../../../../../README.md) / [Signal](../../../README.md) / [subtle](../README.md) / watched
+
+# Variable: watched
+
+```ts
+const watched: unique symbol;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:38

package/api/@xmachines/play-signals/namespaces/Signal/variables/isComputed.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / isComputed
+
+# Variable: isComputed
+
+```ts
+isComputed: (s) => boolean;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:7
+
+## Parameters
+
+| Parameter | Type  |
+| --------- | ----- |
+| `s`       | `any` |
+
+## Returns
+
+`boolean`

package/api/@xmachines/play-signals/namespaces/Signal/variables/isState.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / isState
+
+# Variable: isState
+
+```ts
+isState: (s) => boolean;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:7
+
+## Parameters
+
+| Parameter | Type  |
+| --------- | ----- |
+| `s`       | `any` |
+
+## Returns
+
+`boolean`

package/api/@xmachines/play-signals/namespaces/Signal/variables/isWatcher.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / isWatcher
+
+# Variable: isWatcher
+
+```ts
+isWatcher: (s) => boolean;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:7
+
+## Parameters
+
+| Parameter | Type  |
+| --------- | ----- |
+| `s`       | `any` |
+
+## Returns
+
+`boolean`

package/api/@xmachines/play-signals/type-aliases/WatcherNotify.md

@@ -0,0 +1,32 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / WatcherNotify
+
+# Type Alias: WatcherNotify
+
+```ts
+type WatcherNotify = () => void;
+```
+
+Defined in: [packages/play-signals/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L139)
+
+Notification callback for Signal.subtle.Watcher
+
+Invoked when watched signals change. Use microtask batching pattern to coalesce
+rapid updates (see signal-polyfill README for best practices).
+
+## Returns
+
+`void`
+
+## Example
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const notify: WatcherNotify = () => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		// Process pending signal changes
+	});
+};
+const watcher = new Signal.subtle.Watcher(notify);
+```

package/api/@xmachines/play-solid/README.md

@@ -0,0 +1,311 @@
+[Documentation](../../README.md) / @xmachines/play-solid
+
+# @xmachines/play-solid
+
+**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 solid-js@^1.8.0
+npm install @xmachines/play-solid
+```
+
+## Current Exports
+
+- `PlayRenderer`
+- `PlayRendererProps` (type)
+
+**Peer dependencies:**
+
+- `solid-js` ^1.8.0 - SolidJS runtime
+
+## Quick Start
+
+```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({
+	LoginForm: z.object({ error: z.string().optional() }),
+	Dashboard: z.object({
+		userId: z.string(),
+		username: z.string(),
+	}),
+});
+
+// 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();
+
+// 4. Render UI (actor via props)
+render(
+	() => <PlayRenderer actor={actor} components={components} />,
+	document.getElementById("app")!,
+);
+```
+
+## API Reference
+
+### PlayRenderer
+
+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` - Actor instance with `currentView` signal
+- `components` - Map of component names to SolidJS components
+- `fallback` - Component shown when `currentView` is null
+
+**Behavior:**
+
+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 />`
+
+**Example:**
+
+```tsx
+<PlayRenderer
+	actor={actor}
+	components={{
+		HomePage: (props) => <div>Home</div>,
+		AboutPage: (props) => <div>About</div>,
+	}}
+	fallback={<div>Loading...</div>}
+/>
+```
+
+## Examples
+
+### Component Receiving Props from Catalog
+
+```tsx
+import { PlayRenderer } from "@xmachines/play-solid";
+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: (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
+
+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
+
+**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 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/README.md)** - XState adapter providing actors
+- **[@xmachines/play-catalog](../play-catalog/README.md)** - UI schema validation
+- **[@xmachines/play-solid-router](../play-solid-router/README.md)** - Solid Router integration
+- **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md)** - TanStack Solid Router integration
+- **[@xmachines/play-actor](../play-actor/README.md)** - Actor base
+- **[@xmachines/play-signals](../play-signals/README.md)** - TC39 Signals primitives
+
+## License
+
+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>.
+
+SolidJS renderer for XMachines Play architecture
+
+## Interfaces
+
+- [PlayRendererProps](interfaces/PlayRendererProps.md)
+
+## Variables
+
+- [PlayRenderer](variables/PlayRenderer.md)

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

@@ -0,0 +1,15 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid](../README.md) / PlayRendererProps
+
+# Interface: PlayRendererProps
+
+Defined in: [types.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid/src/types.ts#L20)
+
+Props for PlayRenderer component
+
+## Properties
+
+| Property                                      | Type                                                                                                                                    | Description                                                           | Defined in                                                                                                                                     |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`           | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<`AnyActorLogic`\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) | Actor instance with currentView signal (requires Viewable capability) | [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid/src/types.ts#L22) |
+| <a id="property-components"></a> `components` | `Record`\<`string`, `ValidComponent`\>                                                                                                  | Map of component names to SolidJS components                          | [types.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid/src/types.ts#L25) |
+| <a id="property-fallback"></a> `fallback?`    | `any`                                                                                                                                   | Optional element shown when currentView is null                       | [types.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid/src/types.ts#L28) |