@xmachines/play-signals 1.0.0-beta.9 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Karon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,29 +1,80 @@
 # @xmachines/play-signals
 
-**Canonical Signals substrate for XMachines with Stage 1 API isolation**
+TC39 Signals polyfill for XMachines — fine-grained reactive state primitives that enable glitch-free, subscription-free state propagation in the Play Architecture.
 
-`@xmachines/play-signals` re-exports `Signal` from `signal-polyfill` as the single import boundary for XMachines packages.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
 
-## 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.
+Part of the [xmachines-js monorepo](../../README.md).
 
 ## Installation
 
 ```bash
-npm install @xmachines/play-signals
+pnpm add @xmachines/play-signals
 ```
 
-## Current Exports
+## Overview
+
+This package wraps the [`signal-polyfill`](https://github.com/nicolo-ribaudo/tc39-proposal-signals-polyfill) reference implementation of the [TC39 Signals proposal](https://github.com/tc39/proposal-signals) (Stage 1). It re-exports the full `Signal` namespace and adds a memory-safe `watchSignal` utility, isolating the rest of the codebase from potential Stage 1 API churn.
+
+**All signal imports in the XMachines ecosystem should come from this package**, not directly from `signal-polyfill`, so that polyfill version bumps or API adaptations can be made in one place.
 
-- `Signal` (re-export from `signal-polyfill`)
-- Type exports from `src/types.ts`: `SignalState`, `SignalComputed`, `SignalWatcher`, `SignalOptions`, `ComputedOptions`, `WatcherNotify`
+## Usage
 
-## Quick Start
+### `Signal.State` — writable reactive state
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+
+console.log(count.get()); // 0
+count.set(5);
+console.log(count.get()); // 5
+```
+
+### `Signal.Computed` — lazy memoized derived values
+
+```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  (computed on first access)
+count.set(5);
+console.log(doubled.get()); // 10 (recomputed because dependency changed)
+console.log(doubled.get()); // 10 (memoized — no recomputation)
+```
+
+Computations automatically track every signal accessed inside them. Dynamic branching is fully supported — only signals read in the _current_ execution path are tracked as dependencies.
+
+### `watchSignal` — memory-safe one-shot effect
+
+Use `watchSignal` to subscribe to a `Signal.State` or `Signal.Computed` and receive its value after each change. Updates are coalesced into a single microtask per synchronous batch.
+
+```typescript
+import { Signal, watchSignal } from "@xmachines/play-signals";
+
+const count = new Signal.State(0);
+
+const cleanup = watchSignal(count, (value) => {
+	console.log("count changed:", value);
+});
+
+count.set(1); // → logs "count changed: 1" (via microtask)
+count.set(2); // coalesced with any rapid synchronous changes
+count.set(3); // → logs "count changed: 3" once
+
+// Stop watching
+cleanup();
+```
+
+The returned cleanup function is idempotent — calling it multiple times is safe and will not throw.
+
+### `Signal.subtle.Watcher` — low-level multi-signal observation
+
+For advanced use cases such as framework integrations, the full `Signal.subtle.Watcher` API is available:
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -34,79 +85,74 @@ 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);
+		console.log("signals changed:", pending.length);
+		watcher.watch(...pending); // re-arm for future changes
 	});
 });
 
+watcher.watch(count);
 watcher.watch(doubled);
-doubled.get();
-
-count.set(2);
-
-const dispose = () => {
-	watcher.unwatch(doubled);
-};
 
-void dispose;
+count.set(5); // schedules microtask notification
 ```
 
-## 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)`.
+### Custom equality
 
-Watcher notifications are one-shot. If you do not re-arm, you will miss future updates.
+Both `Signal.State` and `Signal.Computed` accept an `equals` option to control when dependents are notified:
 
-## Cleanup Contract
+```typescript
+import { Signal } from "@xmachines/play-signals";
+import type { SignalOptions } from "@xmachines/play-signals";
 
-Always dispose explicitly. Do not rely on GC-only cleanup guidance.
+const options: SignalOptions<{ name: string; age: number }> = {
+	equals: (a, b) => a.name === b.name && a.age === b.age,
+};
 
-- If you called `watch(...)`, call `unwatch(...)` in teardown.
-- Framework lifecycles (`useEffect` cleanup, `onUnmounted`, `onCleanup`) must unwatch.
-- Bridge lifecycles (`disconnect`, `dispose`) must unwatch and unsubscribe.
+const person = new Signal.State({ name: "Alice", age: 30 }, options);
+// Setting structurally identical value will not notify dependents
+person.set({ name: "Alice", age: 30 });
+```
 
-## Optional Helper Direction
+## API Summary
 
-Raw `Signal` remains canonical. Helper APIs are optional, additive guidance for consistency:
+| Export                         | Kind      | Description                                                                                            |
+| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
+| `Signal`                       | namespace | Full TC39 Signals namespace (`State`, `Computed`, `subtle.Watcher`) re-exported from `signal-polyfill` |
+| `watchSignal(signal, onValue)` | function  | Memory-safe subscription helper; returns a cleanup function                                            |
+| `SignalState<T>`               | interface | Shape of `Signal.State<T>` (`.get()`, `.set()`)                                                        |
+| `SignalComputed<T>`            | interface | Shape of `Signal.Computed<T>` (`.get()`)                                                               |
+| `SignalWatcher`                | interface | Shape of `Signal.subtle.Watcher` (`.watch()`, `.unwatch()`, `.getPending()`)                           |
+| `SignalOptions<T>`             | interface | Options bag for `Signal.State` constructor (`equals?`)                                                 |
+| `ComputedOptions<T>`           | interface | Options bag for `Signal.Computed` constructor (`equals?`)                                              |
+| `WatcherNotify`                | type      | Callback signature for `Signal.subtle.Watcher` notify function                                         |
 
-- `watchSignals(signals, onChange, options)`
-- `createSignalEffect(effect, options)`
-- `toSubscribable(signal, options)`
+## Testing
 
-These helpers are intended to codify lifecycle-safe watcher scheduling and deterministic teardown. They do not replace direct `Signal` usage.
+Run tests for this package in isolation:
 
-## API Surface
+```bash
+# From this package directory
+pnpm test
 
-- `Signal.State<T>`: writable signal state (`get`, `set`)
-- `Signal.Computed<T>`: lazy memoized derivations
-- `Signal.subtle.Watcher`: low-level watcher (`watch`, `unwatch`, `getPending`)
+# Watch mode
+pnpm test -- --watch
+```
 
-Complete generated API docs: [docs/api/@xmachines/play-signals](../../docs/api/@xmachines/play-signals)
+From the monorepo root:
 
-## Architecture Notes
+```bash
+# Run tests for this package
+pnpm --filter @xmachines/play-signals test
 
-- **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.
+# Run with coverage (lines ≥ 90 %, functions ≥ 90 %, branches ≥ 85 %, statements ≥ 90 %)
+pnpm run test:coverage
+```
 
-## Resources
+## Requirements
 
-- [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)
+- **Node.js** `>= 22.0.0`
+- **TypeScript** `5.7+` (for consumers using TypeScript)
 
 ## 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>.
+MIT — see [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -32,7 +32,7 @@
  * 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 [Play RFC](../../docs/rfc/play.md) - Invariant INV-05
  * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
  *
  * @remarks
@@ -46,5 +46,6 @@
  * consuming packages. This architectural decision protects against Stage 1 API churn.
  */
 export { Signal } from "signal-polyfill";
+export { watchSignal } from "./watch-signal.js";
 export type { SignalState, SignalComputed, SignalWatcher, SignalOptions, ComputedOptions, WatcherNotify, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,YAAY,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -32,7 +32,7 @@
  * 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 [Play RFC](../../docs/rfc/play.md) - Invariant INV-05
  * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
  *
  * @remarks
@@ -47,4 +47,5 @@
  */
 // Re-export complete Signal namespace from official polyfill
 export { Signal } from "signal-polyfill";
+export { watchSignal } from "./watch-signal.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,6DAA6D;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/watch-signal.d.ts

@@ -0,0 +1,21 @@
+import { Signal } from "signal-polyfill";
+/**
+ * Subscribe to a single signal using the canonical one-shot watcher lifecycle.
+ *
+ * The callback runs from a queued microtask after pending notifications are
+ * drained, then the watcher re-arms itself so future updates are not missed.
+ * The returned cleanup keeps teardown idempotent by tolerating already-detached
+ * watchers.
+ *
+ * **Memory safety (Phase 29):**
+ * - `disposed` flag prevents post-cleanup callback execution: if cleanup is
+ *   called before a pending microtask fires, the microtask returns early.
+ * - `needsEnqueue` guard dedups rapid synchronous signal changes: only one
+ *   microtask is ever queued per batch of synchronous mutations.
+ *
+ * @param signal - A `Signal.State` or `Signal.Computed` to subscribe to.
+ * @param onValue - Called with the current signal value after each change.
+ * @returns A cleanup function that unregisters the watcher.
+ */
+export declare function watchSignal<T>(signal: Signal.State<T> | Signal.Computed<T>, onValue: (value: T) => void): () => void;
+//# sourceMappingURL=watch-signal.d.ts.map

package/dist/watch-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-signal.d.ts","sourceRoot":"","sources":["../src/watch-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAC5C,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GACzB,MAAM,IAAI,CA0BZ"}

package/dist/watch-signal.js

@@ -0,0 +1,47 @@
+import { Signal } from "signal-polyfill";
+/**
+ * Subscribe to a single signal using the canonical one-shot watcher lifecycle.
+ *
+ * The callback runs from a queued microtask after pending notifications are
+ * drained, then the watcher re-arms itself so future updates are not missed.
+ * The returned cleanup keeps teardown idempotent by tolerating already-detached
+ * watchers.
+ *
+ * **Memory safety (Phase 29):**
+ * - `disposed` flag prevents post-cleanup callback execution: if cleanup is
+ *   called before a pending microtask fires, the microtask returns early.
+ * - `needsEnqueue` guard dedups rapid synchronous signal changes: only one
+ *   microtask is ever queued per batch of synchronous mutations.
+ *
+ * @param signal - A `Signal.State` or `Signal.Computed` to subscribe to.
+ * @param onValue - Called with the current signal value after each change.
+ * @returns A cleanup function that unregisters the watcher.
+ */
+export function watchSignal(signal, onValue) {
+    let disposed = false;
+    let needsEnqueue = true;
+    const watcher = new Signal.subtle.Watcher(() => {
+        if (disposed || !needsEnqueue)
+            return;
+        needsEnqueue = false;
+        queueMicrotask(() => {
+            if (disposed)
+                return;
+            needsEnqueue = true;
+            watcher.getPending();
+            onValue(signal.get());
+            watcher.watch(signal);
+        });
+    });
+    watcher.watch(signal);
+    return () => {
+        disposed = true;
+        try {
+            watcher.unwatch(signal);
+        }
+        catch {
+            // Ignore detached watcher errors to keep cleanup idempotent.
+        }
+    };
+}
+//# sourceMappingURL=watch-signal.js.map

package/dist/watch-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-signal.js","sourceRoot":"","sources":["../src/watch-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAC1B,MAA4C,EAC5C,OAA2B;IAE3B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,YAAY,GAAG,IAAI,CAAC;IAExB,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;QAC9C,IAAI,QAAQ,IAAI,CAAC,YAAY;YAAE,OAAO;QACtC,YAAY,GAAG,KAAK,CAAC;QACrB,cAAc,CAAC,GAAG,EAAE;YACnB,IAAI,QAAQ;gBAAE,OAAO;YACrB,YAAY,GAAG,IAAI,CAAC;YACpB,OAAO,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEtB,OAAO,GAAG,EAAE;QACX,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACJ,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACR,6DAA6D;QAC9D,CAAC;IACF,CAAC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-signals",
-  "version": "1.0.0-beta.9",
+  "version": "1.1.0",
   "private": false,
   "description": "TC39 Signals polyfill for XMachines - Fine-grained reactive state primitives",
   "keywords": [
@@ -10,14 +10,23 @@
     "tc39",
     "xmachines"
   ],
+  "homepage": "https://gitlab.com/xmachin-es/xmachines-js/tree/main/packages/play-signals",
   "license": "MIT",
   "author": "XMachines Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.com/xmachin-es/xmachines-js.git",
+    "directory": "packages/play-signals"
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -29,22 +38,23 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo node_modules/.vite node_modules/.vite-temp",
-    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__ node_modules/.svelte2tsx-* node_modules/.vite*",
     "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
-    "format:check": "oxfmt --check .",
-    "prepublishOnly": "npm run build"
+    "format:check": "oxfmt --check ."
   },
   "dependencies": {
     "signal-polyfill": "^0.2.2"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.9",
-    "vitest": "^4.1.0"
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/node": "^26.2.0",
+    "@vitest/browser-playwright": "^4.1.10",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.79.0",
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=22.0.0"