@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,11 +2,9 @@
 
 # @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
 
@@ -16,9 +14,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
 
@@ -48,11 +46,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";
@@ -71,11 +69,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";
@@ -99,7 +97,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";
@@ -110,7 +108,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 });
 ```
 
@@ -119,13 +117,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
 
@@ -152,36 +150,38 @@ 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
 
 MIT — see [LICENSE](LICENSE).
 
-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.
 
 ## 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());
 });
@@ -192,19 +192,21 @@ count.set(5); // Logs: Count: 5 Doubled: 10
 
 ## See
 
-- [Play RFC](../../../rfc/play.md) - Invariant INV-05
+- [Play RFC](../../../rfc/play.md) - invariant INV-05
 - [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.
+**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.
 
-**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.
+**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.
 
 ## Namespaces
 

package/api/@xmachines/play-signals/functions/watchSignal.md

@@ -6,21 +6,21 @@
 function watchSignal<T>(signal, onValue): () => void;
 ```
 
-Defined in: [packages/play-signals/src/watch-signal.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/watch-signal.ts#L21)
+Defined in: [packages/play-signals/src/watch-signal.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/watch-signal.ts#L21)
 
-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.
 
 ## Type Parameters
 
@@ -30,13 +30,13 @@ watchers.
 
 ## Parameters
 
-| Parameter | Type                                                                                                                        | Description                                             |
-| --------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| `signal`  | \| [`State`](../namespaces/Signal/classes/State.md)\<`T`\> \| [`Computed`](../namespaces/Signal/classes/Computed.md)\<`T`\> | A `Signal.State` or `Signal.Computed` to subscribe to.  |
-| `onValue` | (`value`) => `void`                                                                                                         | Called with the current signal value after each change. |
+| Parameter | Type                                                                                                                        | Description                                                           |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `signal`  | \| [`State`](../namespaces/Signal/classes/State.md)\<`T`\> \| [`Computed`](../namespaces/Signal/classes/Computed.md)\<`T`\> | The `Signal.State` or `Signal.Computed` to subscribe to.              |
+| `onValue` | (`value`) => `void`                                                                                                         | The watcher calls it with the current signal value after each change. |
 
 ## Returns
 
-A cleanup function that unregisters the watcher.
+The cleanup function. It removes the watcher.
 
 () => `void`

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

@@ -2,15 +2,15 @@
 
 # Interface: ComputedOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L84)
+Defined in: [packages/play-signals/src/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L85)
 
-Options for creating Signal.Computed
+The options of a Signal.Computed
 
 ## Param
 
 **equals**
 
-Optional custom equality function for memoization
+The optional equality function of your own, for the memoization
 
 ## Example
 
@@ -31,6 +31,6 @@ const options: ComputedOptions<string> = {
 
 ## 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/v2.0.0/packages/play-signals/src/types.ts#L88) |
+| Property                               | Type                    | Description                                            | Defined in                                                                                                                               |
+| -------------------------------------- | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own, for the memoization | [packages/play-signals/src/types.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L89) |

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

@@ -2,13 +2,13 @@
 
 # Interface: SignalComputed\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L111)
+Defined in: [packages/play-signals/src/types.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L112)
 
-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
 
@@ -20,8 +20,8 @@ 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)
+console.log(doubled.get()); // 10 (the signal computed it again)
+console.log(doubled.get()); // 10 (from the memory, with no new computation)
 ```
 
 ## Type Parameters
@@ -38,12 +38,12 @@ console.log(doubled.get()); // 10 (memoized, not recomputed)
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L117)
+Defined in: [packages/play-signals/src/types.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L118)
 
-Read computed value (recalculates only if dependencies changed)
+Reads the computed value. It computes the value again only after a dependency changed
 
 #### Returns
 
 `T`
 
-Computed value based on current dependencies
+The value from the current dependencies

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

@@ -2,15 +2,15 @@
 
 # Interface: SignalOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L26)
+Defined in: [packages/play-signals/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L27)
 
-Options for creating Signal.State
+The options of a Signal.State
 
 ## Param
 
 **equals**
 
-Optional custom equality function for determining if value changed
+The optional equality function of your own. It decides if the value changed
 
 ## Example
 
@@ -32,6 +32,6 @@ const count = new Signal.State(0, options);
 
 ## 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/v2.0.0/packages/play-signals/src/types.ts#L33) |
+| Property                               | Type                    | Description                                                        | Defined in                                                                                                                               |
+| -------------------------------------- | ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own. It decides if the value changed | [packages/play-signals/src/types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L34) |

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

@@ -2,13 +2,13 @@
 
 # Interface: SignalState\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L53)
+Defined in: [packages/play-signals/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L54)
 
-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
 
@@ -35,15 +35,15 @@ console.log(name.get()); // 'Bob'
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L59)
+Defined in: [packages/play-signals/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L60)
 
-Read current value and track as dependency
+Reads the current value, and tracks the signal as a dependency
 
 #### Returns
 
 `T`
 
-Current value of the signal
+The current value of the signal
 
 ---
 
@@ -53,15 +53,15 @@ Current value of the signal
 set(value): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L66)
+Defined in: [packages/play-signals/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L67)
 
-Write new value and notify watchers if changed
+Writes a new value, and notifies the watchers when the value changed
 
 #### Parameters
 
-| Parameter | Type | Description      |
-| --------- | ---- | ---------------- |
-| `value`   | `T`  | New value to set |
+| Parameter | Type | Description   |
+| --------- | ---- | ------------- |
+| `value`   | `T`  | The new value |
 
 #### Returns
 

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

@@ -2,12 +2,12 @@
 
 # Interface: SignalWatcher
 
-Defined in: [packages/play-signals/src/types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L167)
+Defined in: [packages/play-signals/src/types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L169)
 
-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
 
@@ -27,7 +27,7 @@ const watcher = new Signal.subtle.Watcher(() => {
 watcher.watch(count);
 watcher.watch(doubled);
 
-count.set(5); // Notification scheduled via microtask
+count.set(5); // The watcher schedules the notification in a microtask
 ```
 
 ## Methods
@@ -40,9 +40,9 @@ getPending(): (
   | SignalComputed<unknown>)[];
 ```
 
-Defined in: [packages/play-signals/src/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L187)
+Defined in: [packages/play-signals/src/types.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L189)
 
-Get signals that changed since last check
+Returns the signals that changed after the last check
 
 #### Returns
 
@@ -50,7 +50,7 @@ Get signals that changed since last check
 \| [`SignalState`](SignalState.md)\<`unknown`\>
 \| [`SignalComputed`](SignalComputed.md)\<`unknown`\>)[]
 
-Array of signals that have pending updates
+The array of the signals with an update that waits
 
 ---
 
@@ -60,15 +60,15 @@ Array of signals that have pending updates
 unwatch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L180)
+Defined in: [packages/play-signals/src/types.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L182)
 
-Stop watching a signal
+Stops the watch of one signal
 
 #### Parameters
 
-| Parameter | Type                                                                                                  | Description              |
-| --------- | ----------------------------------------------------------------------------------------------------- | ------------------------ |
-| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | Signal to stop observing |
+| Parameter | Type                                                                                                  | Description         |
+| --------- | ----------------------------------------------------------------------------------------------------- | ------------------- |
+| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | The signal to leave |
 
 #### Returns
 
@@ -82,15 +82,15 @@ Stop watching a signal
 watch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L173)
+Defined in: [packages/play-signals/src/types.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L175)
 
-Start watching a signal for changes
+Starts the watch of one signal
 
 #### Parameters
 
-| Parameter | Type                                                                                                  | Description                           |
-| --------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | Signal to observe (State or Computed) |
+| Parameter | Type                                                                                                  | Description                                  |
+| --------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `signal`  | \| [`SignalState`](SignalState.md)\<`unknown`\> \| [`SignalComputed`](SignalComputed.md)\<`unknown`\> | The signal to observe: a State or a Computed |
 
 #### Returns
 

package/api/@xmachines/play-signals/type-aliases/WatcherNotify.md

@@ -6,12 +6,13 @@
 type WatcherNotify = () => void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-signals/src/types.ts#L139)
+Defined in: [packages/play-signals/src/types.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-signals/src/types.ts#L141)
 
-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.
 
 ## Returns
 
@@ -25,7 +26,7 @@ import { Signal } from "@xmachines/play-signals";
 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);