@xmachines/docs 1.0.0-beta.10

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

@@ -0,0 +1,176 @@
+[Documentation](../../README.md) / @xmachines/play-signals
+
+# @xmachines/play-signals
+
+**Canonical Signals substrate for XMachines with Stage 1 API isolation**
+
+`@xmachines/play-signals` re-exports `Signal` from `signal-polyfill` as the single import boundary for XMachines packages.
+
+## Why This Package Exists
+
+- Keep the raw `Signal` API as the canonical substrate surface.
+- Isolate Stage 1 proposal churn behind one package boundary.
+- Preserve Play invariants: Signal-only reactivity, passive infrastructure, and event-only mutation paths.
+
+This package does not add business behavior to signals. Adapters and renderers observe signals and forward events; they do not mutate business state directly.
+
+## Installation
+
+```bash
+npm install @xmachines/play-signals
+```
+
+## Current Exports
+
+- `Signal` (re-export from `signal-polyfill`)
+- Type exports from `src/types.ts`: `SignalState`, `SignalComputed`, `SignalWatcher`, `SignalOptions`, `ComputedOptions`, `WatcherNotify`
+
+## Quick Start
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+const doubled = new Signal.Computed(() => count.get() * 2);
+
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		for (const signal of pending) {
+			signal.get();
+		}
+		watcher.watch(...pending);
+	});
+});
+
+watcher.watch(doubled);
+doubled.get();
+
+count.set(2);
+
+const dispose = () => {
+	watcher.unwatch(doubled);
+};
+
+void dispose;
+```
+
+## Canonical Watcher Lifecycle
+
+Use one lifecycle pattern everywhere (React, Vue, Solid, router bridges, helper wrappers):
+
+1. `notify` callback runs.
+2. Schedule work with `queueMicrotask`.
+3. Drain `watcher.getPending()`.
+4. Perform reads/effects.
+5. Re-arm watcher with `watch()` or `watch(...signals)`.
+
+Watcher notifications are one-shot. If you do not re-arm, you will miss future updates.
+
+## Cleanup Contract
+
+Always dispose explicitly. Do not rely on GC-only cleanup guidance.
+
+- If you called `watch(...)`, call `unwatch(...)` in teardown.
+- Framework lifecycles (`useEffect` cleanup, `onUnmounted`, `onCleanup`) must unwatch.
+- Bridge lifecycles (`disconnect`, `dispose`) must unwatch and unsubscribe.
+
+## Optional Helper Direction
+
+Raw `Signal` remains canonical. Helper APIs are optional, additive guidance for consistency:
+
+- `watchSignals(signals, onChange, options)`
+- `createSignalEffect(effect, options)`
+- `toSubscribable(signal, options)`
+
+These helpers are intended to codify lifecycle-safe watcher scheduling and deterministic teardown. They do not replace direct `Signal` usage.
+
+## API Surface
+
+- `Signal.State<T>`: writable signal state (`get`, `set`)
+- `Signal.Computed<T>`: lazy memoized derivations
+- `Signal.subtle.Watcher`: low-level watcher (`watch`, `unwatch`, `getPending`)
+
+## Architecture Notes
+
+- **Signal-Only Reactivity (INV-05):** Signals are the reactive substrate.
+- **Passive Infrastructure (INV-04):** Adapters and frameworks only observe/forward.
+- **Actor Authority (INV-01):** Business validity and transitions stay in actors.
+- **Event-only mutation path:** Signals are not a business mutation channel.
+
+## Resources
+
+- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)
+- [signal-polyfill](https://github.com/proposal-signals/signal-polyfill)
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+
+## 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>.
+
+TC39 Signals Polyfill for XMachines Play Architecture
+
+Provides fine-grained reactive state primitives based on the TC39 Signals proposal (Stage 1).
+This package isolates the TC39 polyfill to protect the codebase from Stage 1 API changes.
+
+**Architectural Context:** Implements **Signal-Only Reactivity (INV-05)** by providing
+the reactive primitives that enable Actor-to-Infrastructure communication without
+subscriptions or event emitters. All state propagation in Play Architecture uses
+TC39 Signals for automatic dependency tracking and glitch-free updates.
+
+## Example
+
+Basic Signal usage
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+// Create state signal
+const count = new Signal.State(0);
+
+// Create computed signal
+const doubled = new Signal.Computed(() => count.get() * 2);
+
+// Observe changes
+const watcher = new Signal.subtle.Watcher(() => {
+	console.log("Count:", count.get(), "Doubled:", doubled.get());
+});
+watcher.watch(count);
+
+count.set(5); // Logs: Count: 5 Doubled: 10
+```
+
+## See
+
+- [RFC Play v1 - Invariant INV-05](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md)
+- [TC39 Signals Proposal](https://github.com/tc39/proposal-signals)
+
+## Remarks
+
+**Stage 1 Status:** TC39 Signals is currently Stage 1 in the TC39 process. This package
+uses the official `signal-polyfill` reference implementation to isolate the codebase
+from potential API changes as the proposal evolves. All signal imports should go through
+this package to maintain isolation.
+
+**Why Isolation:** By re-exporting the polyfill through this dedicated package, we can
+update the polyfill version or adapt to API changes in one place without touching
+consuming packages. This architectural decision protects against Stage 1 API churn.
+
+## Namespaces
+
+- [Signal](namespaces/Signal/README.md)
+
+## Interfaces
+
+- [ComputedOptions](interfaces/ComputedOptions.md)
+- [SignalComputed](interfaces/SignalComputed.md)
+- [SignalOptions](interfaces/SignalOptions.md)
+- [SignalState](interfaces/SignalState.md)
+- [SignalWatcher](interfaces/SignalWatcher.md)
+
+## Type Aliases
+
+- [WatcherNotify](type-aliases/WatcherNotify.md)

package/api/@xmachines/play-signals/interfaces/ComputedOptions.md

@@ -0,0 +1,34 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / ComputedOptions
+
+# Interface: ComputedOptions\<T\>
+
+Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L84)
+
+Options for creating Signal.Computed
+
+## Param
+
+Optional custom equality function for memoization
+
+## Example
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+import type { ComputedOptions } from "@xmachines/play-signals";
+
+const options: ComputedOptions<string> = {
+	equals: (a, b) => a.toLowerCase() === b.toLowerCase(),
+};
+```
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Properties
+
+| Property                               | Type                    | Description                              | Defined in                                                                                                                                                                 |
+| -------------------------------------- | ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | Custom equality function for memoization | [packages/play-signals/src/types.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L88) |

package/api/@xmachines/play-signals/interfaces/SignalComputed.md

@@ -0,0 +1,49 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalComputed
+
+# Interface: SignalComputed\<T\>
+
+Defined in: [packages/play-signals/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L111)
+
+Lazily-evaluated, memoized computed signal
+
+Signal.Computed automatically tracks dependencies when its callback is executed.
+The computation is memoized and only re-runs when dependencies change. This enables
+automatic dependency tracking without manual subscription management.
+
+## Example
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+const doubled = new Signal.Computed(() => count.get() * 2);
+
+console.log(doubled.get()); // 0
+count.set(5);
+console.log(doubled.get()); // 10 (recomputed)
+console.log(doubled.get()); // 10 (memoized, not recomputed)
+```
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: [packages/play-signals/src/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L117)
+
+Read computed value (recalculates only if dependencies changed)
+
+#### Returns
+
+`T`
+
+Computed value based on current dependencies

package/api/@xmachines/play-signals/interfaces/SignalOptions.md

@@ -0,0 +1,35 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalOptions
+
+# Interface: SignalOptions\<T\>
+
+Defined in: [packages/play-signals/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L26)
+
+Options for creating Signal.State
+
+## Param
+
+Optional custom equality function for determining if value changed
+
+## Example
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+import type { SignalOptions } from "@xmachines/play-signals";
+
+const options: SignalOptions<number> = {
+	equals: (a, b) => a === b,
+};
+const count = new Signal.State(0, options);
+```
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Properties
+
+| Property                               | Type                    | Description                                               | Defined in                                                                                                                                                                 |
+| -------------------------------------- | ----------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | Custom equality function for determining if value changed | [packages/play-signals/src/types.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L33) |

package/api/@xmachines/play-signals/interfaces/SignalState.md

@@ -0,0 +1,68 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalState
+
+# Interface: SignalState\<T\>
+
+Defined in: [packages/play-signals/src/types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L53)
+
+Writable state signal holding a single reactive value
+
+Signal.State is the fundamental primitive for reactive state. Calling `get()` within
+a computed signal or watcher automatically tracks the state as a dependency. Calling
+`set()` notifies all dependent computations and watchers.
+
+## Example
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const name = new Signal.State("Alice");
+console.log(name.get()); // 'Alice'
+name.set("Bob");
+console.log(name.get()); // 'Bob'
+```
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: [packages/play-signals/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L59)
+
+Read current value and track as dependency
+
+#### Returns
+
+`T`
+
+Current value of the signal
+
+---
+
+### set()
+
+```ts
+set(value): void;
+```
+
+Defined in: [packages/play-signals/src/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L66)
+
+Write new value and notify watchers if changed
+
+#### Parameters
+
+| Parameter | Type | Description      |
+| --------- | ---- | ---------------- |
+| `value`   | `T`  | New value to set |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-signals/interfaces/SignalWatcher.md

@@ -0,0 +1,97 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / SignalWatcher
+
+# Interface: SignalWatcher
+
+Defined in: [packages/play-signals/src/types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L167)
+
+Watcher for observing signal changes and scheduling effects
+
+Signal.subtle.Watcher enables observing multiple signals and batching updates.
+This is the low-level primitive used by frameworks to implement reactive effects.
+
+## Example
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+const doubled = new Signal.Computed(() => count.get() * 2);
+
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		console.log("Signals changed:", pending.length);
+	});
+});
+
+watcher.watch(count);
+watcher.watch(doubled);
+
+count.set(5); // Notification scheduled via microtask
+```
+
+## Methods
+
+### getPending()
+
+```ts
+getPending(): (
+  | SignalState<unknown>
+  | SignalComputed<unknown>)[];
+```
+
+Defined in: [packages/play-signals/src/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L187)
+
+Get signals that changed since last check
+
+#### Returns
+
+(
+\| [`SignalState`](SignalState.md)\<`unknown`\>
+\| [`SignalComputed`](SignalComputed.md)\<`unknown`\>)[]
+
+Array of signals that have pending updates
+
+---
+
+### unwatch()
+
+```ts
+unwatch(signal): void;
+```
+
+Defined in: [packages/play-signals/src/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L180)
+
+Stop watching a signal
+
+#### Parameters
+
+| Parameter | Type                                                                                                  | Description              |
+| --------- | ----------------------------------------------------------------------------------------------------- | ------------------------ |
+| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | Signal to stop observing |
+
+#### Returns
+
+`void`
+
+---
+
+### watch()
+
+```ts
+watch(signal): void;
+```
+
+Defined in: [packages/play-signals/src/types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-signals/src/types.ts#L173)
+
+Start watching a signal for changes
+
+#### Parameters
+
+| Parameter | Type                                                                                                  | Description                           |
+| --------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | Signal to observe (State or Computed) |
+
+#### Returns
+
+`void`

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

@@ -0,0 +1,22 @@
+[Documentation](../../../../README.md) / [@xmachines/play-signals](../../README.md) / Signal
+
+# Signal
+
+## Namespaces
+
+- [subtle](namespaces/subtle/README.md)
+
+## Classes
+
+- [Computed](classes/Computed.md)
+- [State](classes/State.md)
+
+## Interfaces
+
+- [Options](interfaces/Options.md)
+
+## Variables
+
+- [isComputed](variables/isComputed.md)
+- [isState](variables/isState.md)
+- [isWatcher](variables/isWatcher.md)

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

@@ -0,0 +1,52 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / Computed
+
+# Class: Computed\<T\>
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:15
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Constructors
+
+### Constructor
+
+```ts
+new Computed<T>(computation, options?): Computed<T>;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:18
+
+#### Parameters
+
+| Parameter     | Type                                         |
+| ------------- | -------------------------------------------- |
+| `computation` | () => `T`                                    |
+| `options?`    | [`Options`](../interfaces/Options.md)\<`T`\> |
+
+#### Returns
+
+`Computed`\<`T`\>
+
+## Properties
+
+| Property                            | Modifier   | Type                  | Defined in                                        |
+| ----------------------------------- | ---------- | --------------------- | ------------------------------------------------- |
+| <a id="property-node"></a> `[NODE]` | `readonly` | `ComputedNode`\<`T`\> | node_modules/signal-polyfill/dist/wrapper.d.ts:17 |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:19
+
+#### Returns
+
+`T`

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

@@ -0,0 +1,72 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / State
+
+# Class: State\<T\>
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:8
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Constructors
+
+### Constructor
+
+```ts
+new State<T>(initialValue, options?): State<T>;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:11
+
+#### Parameters
+
+| Parameter      | Type                                         |
+| -------------- | -------------------------------------------- |
+| `initialValue` | `T`                                          |
+| `options?`     | [`Options`](../interfaces/Options.md)\<`T`\> |
+
+#### Returns
+
+`State`\<`T`\>
+
+## Properties
+
+| Property                            | Modifier   | Type                | Defined in                                        |
+| ----------------------------------- | ---------- | ------------------- | ------------------------------------------------- |
+| <a id="property-node"></a> `[NODE]` | `readonly` | `SignalNode`\<`T`\> | node_modules/signal-polyfill/dist/wrapper.d.ts:10 |
+
+## Methods
+
+### get()
+
+```ts
+get(): T;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:12
+
+#### Returns
+
+`T`
+
+---
+
+### set()
+
+```ts
+set(newValue): void;
+```
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:13
+
+#### Parameters
+
+| Parameter  | Type |
+| ---------- | ---- |
+| `newValue` | `T`  |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-signals/namespaces/Signal/interfaces/Options.md

@@ -0,0 +1,19 @@
+[Documentation](../../../../../README.md) / [@xmachines/play-signals](../../../README.md) / [Signal](../README.md) / Options
+
+# Interface: Options\<T\>
+
+Defined in: node_modules/signal-polyfill/dist/wrapper.d.ts:41
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## Properties
+
+| Property                                       | Type                             | Defined in                                        |
+| ---------------------------------------------- | -------------------------------- | ------------------------------------------------- |
+| <a id="property-unwatched"></a> `[unwatched]?` | (`this`) => `void`               | node_modules/signal-polyfill/dist/wrapper.d.ts:44 |
+| <a id="property-watched"></a> `[watched]?`     | (`this`) => `void`               | node_modules/signal-polyfill/dist/wrapper.d.ts:43 |
+| <a id="property-equals"></a> `equals?`         | (`this`, `t`, `t2`) => `boolean` | node_modules/signal-polyfill/dist/wrapper.d.ts:42 |

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

@@ -0,0 +1,21 @@
+[Documentation](../../../../../../README.md) / [@xmachines/play-signals](../../../../README.md) / [Signal](../../README.md) / subtle
+
+# subtle
+
+## Classes
+
+- [Watcher](classes/Watcher.md)
+
+## Variables
+
+- [unwatched](variables/unwatched.md)
+- [watched](variables/watched.md)
+
+## Functions
+
+- [currentComputed](functions/currentComputed.md)
+- [hasSinks](functions/hasSinks.md)
+- [hasSources](functions/hasSources.md)
+- [introspectSinks](functions/introspectSinks.md)
+- [introspectSources](functions/introspectSources.md)
+- [untrack](functions/untrack.md)