@xmachines/play-signals 1.0.0-beta.4 → 1.0.0-beta.41

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

@@ -21,6 +21,7 @@ npm install @xmachines/play-signals
 ## Current Exports
 
 - `Signal` (re-export from `signal-polyfill`)
+- `watchSignal(signal, onValue)`
 - Type exports from `src/types.ts`: `SignalState`, `SignalComputed`, `SignalWatcher`, `SignalOptions`, `ComputedOptions`, `WatcherNotify`
 
 ## Quick Start
@@ -53,6 +54,28 @@ const dispose = () => {
 void dispose;
 ```
 
+### `watchSignal()` helper
+
+For the common case of subscribing to one signal with deterministic cleanup, use `watchSignal()`:
+
+```typescript
+import { watchSignal } from "@xmachines/play-signals";
+
+const stopWatching = watchSignal(actor.currentRoute, (route) => {
+	console.log("Route changed:", route);
+});
+
+stopWatching();
+```
+
+`watchSignal()` is memory-safe:
+
+- Calling the returned cleanup before a pending microtask fires will **not** invoke the callback — a `disposed` flag prevents use-after-free when components unmount with in-flight updates.
+- Rapid synchronous signal changes coalesce to **one** microtask (`needsEnqueue` guard) — the callback receives the latest value only.
+- Calling the cleanup multiple times is idempotent (no throw).
+
+`watchSignal()` preserves the same canonical watcher lifecycle described below. It is an optional helper for adapter and renderer code; raw `Signal` APIs remain the base substrate.
+
 ## Canonical Watcher Lifecycle
 
 Use one lifecycle pattern everywhere (React, Vue, Solid, router bridges, helper wrappers):
@@ -73,23 +96,12 @@ Always dispose explicitly. Do not rely on GC-only cleanup guidance.
 - 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)
+- `watchSignal(signal, onValue)`: lifecycle-safe single-signal subscription helper
 
 ## Architecture Notes
 
@@ -102,8 +114,11 @@ Complete generated API docs: [docs/api/@xmachines/play-signals](../../docs/api/@
 
 - [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)
+- [Play RFC](../docs/rfc/play.md)
 
 ## License
 
-MIT
+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>.

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.4",
+  "version": "1.0.0-beta.41",
   "private": false,
   "description": "TC39 Signals polyfill for XMachines - Fine-grained reactive state primitives",
   "keywords": [
@@ -10,16 +10,25 @@
     "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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
@@ -29,9 +38,8 @@
   },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__ node_modules/.svelte2tsx-*",
+    "test": "vitest",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
@@ -42,8 +50,11 @@
     "signal-polyfill": "^0.2.2"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@xmachines/shared": "1.0.0-beta.4"
+    "@types/node": "^25.6.0",
+    "@xmachines/shared": "1.0.0-beta.41",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0",
+    "vitest": "^4.1.4"
   },
   "engines": {
     "node": ">=22.0.0"