@xmachines/docs 1.0.0-beta.16 → 1.0.0-beta.17

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

@@ -23,6 +23,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
@@ -55,6 +56,22 @@ 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()` 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):
@@ -75,21 +92,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`)
+- `watchSignal(signal, onValue)`: lifecycle-safe single-signal subscription helper
 
 ## Architecture Notes
 
@@ -174,3 +182,7 @@ consuming packages. This architectural decision protects against Stage 1 API chu
 ## Type Aliases
 
 - [WatcherNotify](type-aliases/WatcherNotify.md)
+
+## Functions
+
+- [watchSignal](functions/watchSignal.md)

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

@@ -0,0 +1,35 @@
+[Documentation](../../../README.md) / [@xmachines/play-signals](../README.md) / watchSignal
+
+# Function: watchSignal()
+
+```ts
+function watchSignal<T>(signal, onValue): () => void;
+```
+
+Defined in: [packages/play-signals/src/watch-signal.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/watch-signal.ts#L15)
+
+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.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+## 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. |
+
+## Returns
+
+A cleanup function that unregisters the watcher.
+
+() => `void`

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

@@ -2,7 +2,7 @@
 
 # Interface: ComputedOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L84)
+Defined in: [packages/play-signals/src/types.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L84)
 
 Options for creating Signal.Computed
 
@@ -31,4 +31,4 @@ const options: ComputedOptions<string> = {
 
 | 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/v1.0.0-beta.16/packages/play-signals/src/types.ts#L88) |
+| <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/v1.0.0-beta.17/packages/play-signals/src/types.ts#L88) |

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

@@ -2,7 +2,7 @@
 
 # Interface: SignalComputed\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L111)
+Defined in: [packages/play-signals/src/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L111)
 
 Lazily-evaluated, memoized computed signal
 
@@ -38,7 +38,7 @@ 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/v1.0.0-beta.16/packages/play-signals/src/types.ts#L117)
+Defined in: [packages/play-signals/src/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L117)
 
 Read computed value (recalculates only if dependencies changed)
 

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

@@ -2,7 +2,7 @@
 
 # Interface: SignalOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L26)
+Defined in: [packages/play-signals/src/types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L26)
 
 Options for creating Signal.State
 
@@ -32,4 +32,4 @@ const count = new Signal.State(0, options);
 
 | 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/v1.0.0-beta.16/packages/play-signals/src/types.ts#L33) |
+| <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/v1.0.0-beta.17/packages/play-signals/src/types.ts#L33) |

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

@@ -2,7 +2,7 @@
 
 # Interface: SignalState\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L53)
+Defined in: [packages/play-signals/src/types.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L53)
 
 Writable state signal holding a single reactive value
 
@@ -35,7 +35,7 @@ console.log(name.get()); // 'Bob'
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L59)
+Defined in: [packages/play-signals/src/types.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L59)
 
 Read current value and track as dependency
 
@@ -53,7 +53,7 @@ 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/v1.0.0-beta.16/packages/play-signals/src/types.ts#L66)
+Defined in: [packages/play-signals/src/types.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L66)
 
 Write new value and notify watchers if changed
 

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

@@ -2,7 +2,7 @@
 
 # Interface: SignalWatcher
 
-Defined in: [packages/play-signals/src/types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L167)
+Defined in: [packages/play-signals/src/types.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L167)
 
 Watcher for observing signal changes and scheduling effects
 
@@ -40,7 +40,7 @@ getPending(): (
   | SignalComputed<unknown>)[];
 ```
 
-Defined in: [packages/play-signals/src/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L187)
+Defined in: [packages/play-signals/src/types.ts:187](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L187)
 
 Get signals that changed since last check
 
@@ -60,7 +60,7 @@ 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/v1.0.0-beta.16/packages/play-signals/src/types.ts#L180)
+Defined in: [packages/play-signals/src/types.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L180)
 
 Stop watching a signal
 
@@ -82,7 +82,7 @@ Stop watching a signal
 watch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L173)
+Defined in: [packages/play-signals/src/types.ts:173](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L173)
 
 Start watching a signal for changes
 

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

@@ -6,7 +6,7 @@
 type WatcherNotify = () => void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.16/packages/play-signals/src/types.ts#L139)
+Defined in: [packages/play-signals/src/types.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.17/packages/play-signals/src/types.ts#L139)
 
 Notification callback for Signal.subtle.Watcher