@xmachines/play-signals 1.0.0-beta.1

package/README.md

@@ -0,0 +1,109 @@
+# @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`)
+
+Complete generated API docs: [docs/api/@xmachines/play-signals](../../docs/api/@xmachines/play-signals)
+
+## 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
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ * @module @xmachines/play-signals
+ *
+ * @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 {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1 - Invariant INV-05}
+ * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
+ *
+ * @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.
+ */
+export { Signal } from "signal-polyfill";
+export type { SignalState, SignalComputed, SignalWatcher, SignalOptions, ComputedOptions, WatcherNotify, } 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGzC,YAAY,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ * @module @xmachines/play-signals
+ *
+ * @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 {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1 - Invariant INV-05}
+ * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
+ *
+ * @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.
+ */
+// Re-export complete Signal namespace from official polyfill
+export { Signal } from "signal-polyfill";
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,6DAA6D;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Type definitions for TC39 Signals API
+ *
+ * These types align with the signal-polyfill implementation and TC39 proposal.
+ * Note: Signal is Stage 1 - API may change in future spec updates.
+ *
+ * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
+ */
+/**
+ * Options for creating Signal.State
+ *
+ * @param equals - 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);
+ * ```
+ */
+export interface SignalOptions<T> {
+    /**
+     * Custom equality function for determining if value changed
+     * @param a - Previous value
+     * @param b - New value
+     * @returns true if values are equal (no notification needed)
+     */
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * 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'
+ * ```
+ */
+export interface SignalState<T> {
+    /**
+     * Read current value and track as dependency
+     *
+     * @returns Current value of the signal
+     */
+    get(): T;
+    /**
+     * Write new value and notify watchers if changed
+     *
+     * @param value - New value to set
+     */
+    set(value: T): void;
+}
+/**
+ * Options for creating Signal.Computed
+ *
+ * @param equals - 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()
+ * };
+ * ```
+ */
+export interface ComputedOptions<T> {
+    /**
+     * Custom equality function for memoization
+     */
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * 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)
+ * ```
+ */
+export interface SignalComputed<T> {
+    /**
+     * Read computed value (recalculates only if dependencies changed)
+     *
+     * @returns Computed value based on current dependencies
+     */
+    get(): T;
+}
+/**
+ * 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).
+ *
+ * @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);
+ * ```
+ */
+export type WatcherNotify = () => void;
+/**
+ * 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
+ * ```
+ */
+export interface SignalWatcher {
+    /**
+     * Start watching a signal for changes
+     *
+     * @param signal - Signal to observe (State or Computed)
+     */
+    watch(signal: SignalState<unknown> | SignalComputed<unknown>): void;
+    /**
+     * Stop watching a signal
+     *
+     * @param signal - Signal to stop observing
+     */
+    unwatch(signal: SignalState<unknown> | SignalComputed<unknown>): void;
+    /**
+     * Get signals that changed since last check
+     *
+     * @returns Array of signals that have pending updates
+     */
+    getPending(): Array<SignalState<unknown> | SignalComputed<unknown>>;
+}
+//# 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;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,GAAG,IAAI,CAAC,CAAC;IAET;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAChC;;;;OAIG;IACH,GAAG,IAAI,CAAC,CAAC;CACT;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAEpE;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAEtE;;;;OAIG;IACH,UAAU,IAAI,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CACpE"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for TC39 Signals API
+ *
+ * These types align with the signal-polyfill implementation and TC39 proposal.
+ * Note: Signal is Stage 1 - API may change in future spec updates.
+ *
+ * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
+ */
+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;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@xmachines/play-signals",
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "description": "TC39 Signals polyfill for XMachines - Fine-grained reactive state primitives",
+  "keywords": [
+    "reactive",
+    "signals",
+    "state-management",
+    "tc39",
+    "xmachines"
+  ],
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "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",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "signal-polyfill": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ * @module @xmachines/play-signals
+ *
+ * @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 {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1 - Invariant INV-05}
+ * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
+ *
+ * @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.
+ */
+
+// Re-export complete Signal namespace from official polyfill
+export { Signal } from "signal-polyfill";
+
+// Re-export TypeScript types for convenience
+export type {
+	SignalState,
+	SignalComputed,
+	SignalWatcher,
+	SignalOptions,
+	ComputedOptions,
+	WatcherNotify,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,188 @@
+/**
+ * Type definitions for TC39 Signals API
+ *
+ * These types align with the signal-polyfill implementation and TC39 proposal.
+ * Note: Signal is Stage 1 - API may change in future spec updates.
+ *
+ * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
+ */
+
+/**
+ * Options for creating Signal.State
+ *
+ * @param equals - 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);
+ * ```
+ */
+export interface SignalOptions<T> {
+	/**
+	 * Custom equality function for determining if value changed
+	 * @param a - Previous value
+	 * @param b - New value
+	 * @returns true if values are equal (no notification needed)
+	 */
+	equals?: (a: T, b: T) => boolean;
+}
+
+/**
+ * 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'
+ * ```
+ */
+export interface SignalState<T> {
+	/**
+	 * Read current value and track as dependency
+	 *
+	 * @returns Current value of the signal
+	 */
+	get(): T;
+
+	/**
+	 * Write new value and notify watchers if changed
+	 *
+	 * @param value - New value to set
+	 */
+	set(value: T): void;
+}
+
+/**
+ * Options for creating Signal.Computed
+ *
+ * @param equals - 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()
+ * };
+ * ```
+ */
+export interface ComputedOptions<T> {
+	/**
+	 * Custom equality function for memoization
+	 */
+	equals?: (a: T, b: T) => boolean;
+}
+
+/**
+ * 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)
+ * ```
+ */
+export interface SignalComputed<T> {
+	/**
+	 * Read computed value (recalculates only if dependencies changed)
+	 *
+	 * @returns Computed value based on current dependencies
+	 */
+	get(): T;
+}
+
+/**
+ * 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).
+ *
+ * @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);
+ * ```
+ */
+export type WatcherNotify = () => void;
+
+/**
+ * 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
+ * ```
+ */
+export interface SignalWatcher {
+	/**
+	 * Start watching a signal for changes
+	 *
+	 * @param signal - Signal to observe (State or Computed)
+	 */
+	watch(signal: SignalState<unknown> | SignalComputed<unknown>): void;
+
+	/**
+	 * Stop watching a signal
+	 *
+	 * @param signal - Signal to stop observing
+	 */
+	unwatch(signal: SignalState<unknown> | SignalComputed<unknown>): void;
+
+	/**
+	 * Get signals that changed since last check
+	 *
+	 * @returns Array of signals that have pending updates
+	 */
+	getPending(): Array<SignalState<unknown> | SignalComputed<unknown>>;
+}