@xmachines/play-signals 2.0.0 → 2.1.0

package/README.md

@@ -1,10 +1,8 @@
 # @xmachines/play-signals
 
-TC39 Signals polyfill for XMachines — fine-grained reactive state primitives that enable glitch-free, subscription-free state propagation in the Play Architecture.
+TC39 Signals polyfill for XMachines. It gives the Play Architecture fine-grained reactive state primitives. The primitives propagate state without a glitch and without a subscription.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
-
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
 
 ## Installation
 
@@ -14,9 +12,9 @@ pnpm add @xmachines/play-signals
 
 ## 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.
+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 complete `Signal` namespace, and it adds the memory-safe `watchSignal` utility. The wrapper keeps the rest of the code away from a Stage 1 API that can still change.
 
-**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.
+**Import every signal in the XMachines ecosystem from this package**, not from `signal-polyfill`. One import point keeps each polyfill update and each API change in one place.
 
 ## Usage
 
@@ -46,11 +44,11 @@ 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.
+A computation tracks each signal that it reads. A dynamic branch is safe: the computation keeps only the signals of the _current_ execution path as its 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.
+Use `watchSignal` to subscribe to a `Signal.State` or to a `Signal.Computed`. The callback receives the value after each change. `watchSignal` groups the updates of one synchronous batch into a single microtask.
 
 ```typescript
 import { Signal, watchSignal } from "@xmachines/play-signals";
@@ -69,11 +67,11 @@ count.set(3); // → logs "count changed: 3" once
 cleanup();
 ```
 
-The returned cleanup function is idempotent — calling it multiple times is safe and will not throw.
+The cleanup function is idempotent. A second call is safe, and it does 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:
+Advanced code, such as a framework integration, can use the complete `Signal.subtle.Watcher` API:
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -97,7 +95,7 @@ count.set(5); // schedules microtask notification
 
 ### Custom equality
 
-Both `Signal.State` and `Signal.Computed` accept an `equals` option to control when dependents are notified:
+Both `Signal.State` and `Signal.Computed` accept an `equals` option. The option controls when a signal notifies its dependents:
 
 ```typescript
 import { Signal } from "@xmachines/play-signals";
@@ -108,7 +106,7 @@ const options: SignalOptions<{ name: string; age: number }> = {
 };
 
 const person = new Signal.State({ name: "Alice", age: 30 }, options);
-// Setting structurally identical value will not notify dependents
+// A structurally identical value does not notify the dependents
 person.set({ name: "Alice", age: 30 });
 ```
 
@@ -117,13 +115,13 @@ person.set({ name: "Alice", age: 30 });
 | 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                                            |
+| `watchSignal(signal, onValue)` | function  | The memory-safe subscription helper. It 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                                         |
+| `SignalOptions<T>`             | interface | The options object for the `Signal.State` constructor (`equals?`)                                      |
+| `ComputedOptions<T>`           | interface | The options object for the `Signal.Computed` constructor (`equals?`)                                   |
+| `WatcherNotify`                | type      | The callback signature of the `Signal.subtle.Watcher` notify function                                  |
 
 ## Testing
 
@@ -150,7 +148,7 @@ pnpm run test:coverage
 ## Requirements
 
 - **Node.js** `>= 22.0.0`
-- **TypeScript** `5.7+` (for consumers using TypeScript)
+- **TypeScript** `5.7+` (for a consumer that uses TypeScript)
 
 ## License
 

package/dist/index.d.ts

@@ -1,29 +1,31 @@
 /**
- * TC39 Signals Polyfill for XMachines Play Architecture
+ * The TC39 Signals polyfill of the 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.
+ * This package gives you the fine-grained reactive state primitives of the TC39
+ * Signals proposal (Stage 1). It keeps the TC39 polyfill in one place, and it
+ * therefore protects the code from a change of the Stage 1 API.
  *
- * **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.
+ * **Architectural context:** the package implements **Signal-Only Reactivity
+ * (INV-05)**. It gives the reactive primitives that carry the communication from
+ * the Actor to the infrastructure, without a subscription and without an event
+ * emitter. Every propagation of state in the Play Architecture uses a TC39 Signal,
+ * which tracks each dependency and updates without a glitch.
  *
  * @packageDocumentation
  * @module @xmachines/play-signals
  *
  * @example
- * Basic Signal usage
+ * The basic use of a signal
  * ```typescript
  * import { Signal } from "@xmachines/play-signals";
  *
- * // Create state signal
+ * // Create a state signal
  * const count = new Signal.State(0);
  *
- * // Create computed signal
+ * // Create a computed signal
  * const doubled = new Signal.Computed(() => count.get() * 2);
  *
- * // Observe changes
+ * // Observe the changes
  * const watcher = new Signal.subtle.Watcher(() => {
  *   console.log('Count:', count.get(), 'Doubled:', doubled.get());
  * });
@@ -32,18 +34,20 @@
  * count.set(5); // Logs: Count: 5 Doubled: 10
  * ```
  *
- * @see [Play RFC](../../docs/rfc/play.md) - 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
- * **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.
+ * **Stage 1 status:** TC39 Signals is at Stage 1 in the TC39 process now. This
+ * package uses the official `signal-polyfill` reference implementation. The code
+ * therefore stays separate from an API that can change while the proposal
+ * develops. Import every signal through this package, and the separation stays
+ * complete.
+ *
+ * **The reason for the separation:** this dedicated package re-exports the
+ * polyfill. Therefore one place holds each new polyfill version and each change of
+ * the API, and no consuming package changes. This architectural decision protects
+ * the code from a change of the Stage 1 API.
  */
 export { Signal } from "signal-polyfill";
 export { watchSignal } from "./watch-signal.js";

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;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;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

@@ -1,29 +1,31 @@
 /**
- * TC39 Signals Polyfill for XMachines Play Architecture
+ * The TC39 Signals polyfill of the 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.
+ * This package gives you the fine-grained reactive state primitives of the TC39
+ * Signals proposal (Stage 1). It keeps the TC39 polyfill in one place, and it
+ * therefore protects the code from a change of the Stage 1 API.
  *
- * **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.
+ * **Architectural context:** the package implements **Signal-Only Reactivity
+ * (INV-05)**. It gives the reactive primitives that carry the communication from
+ * the Actor to the infrastructure, without a subscription and without an event
+ * emitter. Every propagation of state in the Play Architecture uses a TC39 Signal,
+ * which tracks each dependency and updates without a glitch.
  *
  * @packageDocumentation
  * @module @xmachines/play-signals
  *
  * @example
- * Basic Signal usage
+ * The basic use of a signal
  * ```typescript
  * import { Signal } from "@xmachines/play-signals";
  *
- * // Create state signal
+ * // Create a state signal
  * const count = new Signal.State(0);
  *
- * // Create computed signal
+ * // Create a computed signal
  * const doubled = new Signal.Computed(() => count.get() * 2);
  *
- * // Observe changes
+ * // Observe the changes
  * const watcher = new Signal.subtle.Watcher(() => {
  *   console.log('Count:', count.get(), 'Doubled:', doubled.get());
  * });
@@ -32,20 +34,22 @@
  * count.set(5); // Logs: Count: 5 Doubled: 10
  * ```
  *
- * @see [Play RFC](../../docs/rfc/play.md) - 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
- * **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.
+ * **Stage 1 status:** TC39 Signals is at Stage 1 in the TC39 process now. This
+ * package uses the official `signal-polyfill` reference implementation. The code
+ * therefore stays separate from an API that can change while the proposal
+ * develops. Import every signal through this package, and the separation stays
+ * complete.
+ *
+ * **The reason for the separation:** this dedicated package re-exports the
+ * polyfill. Therefore one place holds each new polyfill version and each change of
+ * the API, and no consuming package changes. This architectural decision protects
+ * the code from a change of the Stage 1 API.
  */
-// Re-export complete Signal namespace from official polyfill
+// Re-export the complete Signal namespace of the 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;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,mEAAmE;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types.d.ts

@@ -1,15 +1,16 @@
 /**
- * Type definitions for TC39 Signals API
+ * The type definitions of the 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.
+ * These types follow the signal-polyfill implementation and the TC39 proposal.
+ * Note: Signal is at Stage 1, and a later version of the specification can change
+ * the API.
  *
  * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
  */
 /**
- * Options for creating Signal.State
+ * The options of a Signal.State
  *
- * @param equals - Optional custom equality function for determining if value changed
+ * @param equals - The optional equality function of your own. It decides if the value changed
  *
  * @example
  * ```typescript
@@ -24,19 +25,19 @@
  */
 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)
+     * The equality function of your own. It decides if the value changed
+     * @param a - The previous value
+     * @param b - The new value
+     * @returns true when the two values are equal, and no notification is necessary
      */
     equals?: (a: T, b: T) => boolean;
 }
 /**
- * Writable state signal holding a single reactive value
+ * The writable state signal. It holds one 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.
+ * Signal.State is the base primitive of a reactive state. A `get()` call inside a
+ * computed signal or inside a watcher tracks the state as a dependency. A `set()`
+ * call notifies every computation and every watcher that depends on the state.
  *
  * @example
  * ```typescript
@@ -50,22 +51,22 @@ export interface SignalOptions<T> {
  */
 export interface SignalState<T> {
     /**
-     * Read current value and track as dependency
+     * Reads the current value, and tracks the signal as a dependency
      *
-     * @returns Current value of the signal
+     * @returns The current value of the signal
      */
     get(): T;
     /**
-     * Write new value and notify watchers if changed
+     * Writes a new value, and notifies the watchers when the value changed
      *
-     * @param value - New value to set
+     * @param value - The new value
      */
     set(value: T): void;
 }
 /**
- * Options for creating Signal.Computed
+ * The options of a Signal.Computed
  *
- * @param equals - Optional custom equality function for memoization
+ * @param equals - The optional equality function of your own, for the memoization
  *
  * @example
  * ```typescript
@@ -79,16 +80,16 @@ export interface SignalState<T> {
  */
 export interface ComputedOptions<T> {
     /**
-     * Custom equality function for memoization
+     * The equality function of your own, for the memoization
      */
     equals?: (a: T, b: T) => boolean;
 }
 /**
- * Lazily-evaluated, memoized computed signal
+ * The computed signal. It evaluates late, and it memoizes the result
  *
- * 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.
+ * Signal.Computed tracks each dependency when it runs its callback. It memoizes the
+ * result, and it runs the callback again only after a dependency changes. It
+ * therefore tracks each dependency for you, and you manage no subscription.
  *
  * @example
  * ```typescript
@@ -99,23 +100,24 @@ export interface ComputedOptions<T> {
  *
  * console.log(doubled.get()); // 0
  * count.set(5);
- * console.log(doubled.get()); // 10 (recomputed)
- * console.log(doubled.get()); // 10 (memoized, not recomputed)
+ * console.log(doubled.get()); // 10 (the signal computed it again)
+ * console.log(doubled.get()); // 10 (from the memory, with no new computation)
  * ```
  */
 export interface SignalComputed<T> {
     /**
-     * Read computed value (recalculates only if dependencies changed)
+     * Reads the computed value. It computes the value again only after a dependency changed
      *
-     * @returns Computed value based on current dependencies
+     * @returns The value from the current dependencies
      */
     get(): T;
 }
 /**
- * Notification callback for Signal.subtle.Watcher
+ * The notification callback of a Signal.subtle.Watcher
  *
- * Invoked when watched signals change. Use microtask batching pattern to coalesce
- * rapid updates (see signal-polyfill README for best practices).
+ * The watcher calls it after a signal that it watches changes. Use the microtask
+ * batching pattern to group rapid updates. The README of signal-polyfill gives the
+ * best practice.
  *
  * @example
  * ```typescript
@@ -124,7 +126,7 @@ export interface SignalComputed<T> {
  * const notify: WatcherNotify = () => {
  *   queueMicrotask(() => {
  *     const pending = watcher.getPending();
- *     // Process pending signal changes
+ *     // Process the signal changes that wait
  *   });
  * };
  * const watcher = new Signal.subtle.Watcher(notify);
@@ -132,10 +134,10 @@ export interface SignalComputed<T> {
  */
 export type WatcherNotify = () => void;
 /**
- * Watcher for observing signal changes and scheduling effects
+ * The watcher. It observes each signal change and schedules an effect
  *
- * Signal.subtle.Watcher enables observing multiple signals and batching updates.
- * This is the low-level primitive used by frameworks to implement reactive effects.
+ * Signal.subtle.Watcher observes more than one signal, and it groups the updates.
+ * It is the low-level primitive, and a framework uses it to make a reactive effect.
  *
  * @example
  * ```typescript
@@ -154,26 +156,26 @@ export type WatcherNotify = () => void;
  * watcher.watch(count);
  * watcher.watch(doubled);
  *
- * count.set(5); // Notification scheduled via microtask
+ * count.set(5); // The watcher schedules the notification in a microtask
  * ```
  */
 export interface SignalWatcher {
     /**
-     * Start watching a signal for changes
+     * Starts the watch of one signal
      *
-     * @param signal - Signal to observe (State or Computed)
+     * @param signal - The signal to observe: a State or a Computed
      */
     watch(signal: SignalState<unknown> | SignalComputed<unknown>): void;
     /**
-     * Stop watching a signal
+     * Stops the watch of one signal
      *
-     * @param signal - Signal to stop observing
+     * @param signal - The signal to leave
      */
     unwatch(signal: SignalState<unknown> | SignalComputed<unknown>): void;
     /**
-     * Get signals that changed since last check
+     * Returns the signals that changed after the last check
      *
-     * @returns Array of signals that have pending updates
+     * @returns The array of the signals with an update that waits
      */
     getPending(): Array<SignalState<unknown> | SignalComputed<unknown>>;
 }

package/dist/types.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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;;;;;;;;;;;;;;;;;;;GAmBG;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

@@ -1,8 +1,9 @@
 /**
- * Type definitions for TC39 Signals API
+ * The type definitions of the 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.
+ * These types follow the signal-polyfill implementation and the TC39 proposal.
+ * Note: Signal is at Stage 1, and a later version of the specification can change
+ * the API.
  *
  * @see {@link https://github.com/tc39/proposal-signals | TC39 Signals Proposal}
  */

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/watch-signal.d.ts

@@ -1,21 +1,21 @@
 import { Signal } from "signal-polyfill";
 /**
- * Subscribe to a single signal using the canonical one-shot watcher lifecycle.
+ * Subscribes to one signal, with 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.
+ * The callback runs from a microtask in the queue, after the watcher drains the
+ * notifications that wait. The watcher then arms itself again, so that it misses no
+ * later update. The cleanup function is idempotent, because it accepts a watcher
+ * that is detached already.
  *
  * **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.
+ * - The `disposed` flag stops a callback after the cleanup: the microtask returns at
+ *   once when the cleanup runs before the microtask fires.
+ * - The `needsEnqueue` guard removes the duplicates of rapid synchronous signal
+ *   changes: one batch of synchronous changes queues one microtask only.
  *
- * @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.
+ * @param signal - The `Signal.State` or `Signal.Computed` to subscribe to.
+ * @param onValue - The watcher calls it with the current signal value after each change.
+ * @returns The cleanup function. It removes 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.js

@@ -1,21 +1,21 @@
 import { Signal } from "signal-polyfill";
 /**
- * Subscribe to a single signal using the canonical one-shot watcher lifecycle.
+ * Subscribes to one signal, with 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.
+ * The callback runs from a microtask in the queue, after the watcher drains the
+ * notifications that wait. The watcher then arms itself again, so that it misses no
+ * later update. The cleanup function is idempotent, because it accepts a watcher
+ * that is detached already.
  *
  * **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.
+ * - The `disposed` flag stops a callback after the cleanup: the microtask returns at
+ *   once when the cleanup runs before the microtask fires.
+ * - The `needsEnqueue` guard removes the duplicates of rapid synchronous signal
+ *   changes: one batch of synchronous changes queues one microtask only.
  *
- * @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.
+ * @param signal - The `Signal.State` or `Signal.Computed` to subscribe to.
+ * @param onValue - The watcher calls it with the current signal value after each change.
+ * @returns The cleanup function. It removes the watcher.
  */
 export function watchSignal(signal, onValue) {
     let disposed = false;
@@ -40,7 +40,7 @@ export function watchSignal(signal, onValue) {
             watcher.unwatch(signal);
         }
         catch {
-            // Ignore detached watcher errors to keep cleanup idempotent.
+            // Ignore an error of a detached watcher. The cleanup therefore stays idempotent.
         }
     };
 }

package/dist/watch-signal.js.map

@@ -1 +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"}
+{"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,iFAAiF;QAClF,CAAC;IACF,CAAC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-signals",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "TC39 Signals polyfill for XMachines - Fine-grained reactive state primitives",
   "keywords": [
@@ -41,6 +41,7 @@
     "build": "vite build && tsc --build",
     "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__ node_modules/.svelte2tsx-* node_modules/.vite*",
     "test": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",