@xaendar/signals 0.9.18 → 0.9.22

package/dist/xaendar-signals.js

@@ -0,0 +1,964 @@
+(function(global, factory) {
+	typeof exports === "object" && typeof module !== "undefined" ? factory(exports, require("@xaendar/common")) : typeof define === "function" && define.amd ? define(["exports", "@xaendar/common"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global["@xaendar/signals"] = {}, global._xaendar_common));
+})(this, function(exports, _xaendar_common) {
+	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+	//#region ../packages/signals/src/lib/utils/globals/globals.ts
+	/**
+	* Global state for the signals runtime.
+	* Tracks the currently computing `Computed` instance, whether the state is frozen,
+	* and the current generation counter.
+	*
+	* @internal
+	*/
+	var GLOBAL_STATE = {
+		computing: null,
+		frozen: false
+	};
+	var computingStack = new _xaendar_common.Stack();
+	/**
+	* Pushes a `Computed` instance onto the computing stack and sets it as the
+	* currently active computation in `GLOBAL_STATE`.
+	*
+	* Should be called before executing a computed function to register
+	* dependency tracking.
+	*
+	* @param computed - The `Computed` instance entering the computation phase.
+	* @internal
+	*/
+	function pushComputed(computed) {
+		computingStack.push(computed);
+		GLOBAL_STATE.computing = computed;
+	}
+	/**
+	* Pops the most recent `Computed` instance from the computing stack and
+	* restores the previous one as the active computation in `GLOBAL_STATE`.
+	*
+	* Should be called after a computed function finishes executing.
+	*
+	* @internal
+	*/
+	function popComputed() {
+		computingStack.pop();
+		GLOBAL_STATE.computing = computingStack[computingStack.length - 1] ?? null;
+	}
+	//#endregion
+	//#region ../packages/signals/src/lib/utils/private-symbol/private-symbol.ts
+	/**
+	* Symbol not available in public API,
+	* used to call internal methods of `State` and `Computed` from `Watcher` without exposing them in the public API.
+	*
+	* @internal
+	*/
+	var PRIVATE = Symbol("signals-private");
+	/**
+	* Asserts that the provided symbol matches the internal {@link PRIVATE} symbol,
+	* ensuring the caller has access to internal APIs.
+	*
+	* Throws if the symbol does not match, preventing external code from
+	* invoking methods intended for internal use only.
+	*
+	* @param symbol - The symbol to validate against {@link PRIVATE}.
+	* @throws {Error} If `symbol` does not match {@link PRIVATE}.
+	* @internal
+	*/
+	function assertPrivateContext(symbol) {
+		if (symbol !== PRIVATE) throw new Error("Invalid symbol");
+	}
+	//#endregion
+	//#region ../packages/signals/src/lib/utils/dev-mode/dev-mode.ts
+	/** 
+	* Whether the library is runnign in development mode
+	* Used to log extra information for example
+	* - Invalid transition states for {@link Computed} or {@link Watcher}  
+	*/
+	var devMode = false;
+	/**
+	* Sets the development mode flag.
+	* @param mode - `true` to enable dev mode, `false` to disable it.
+	*/
+	function setDevMode(mode) {
+		devMode = mode;
+	}
+	/**
+	* Returns the current development mode state.
+	* @returns `true` if dev mode is enabled, `false` otherwise.
+	*/
+	function isDevMode() {
+		return devMode;
+	}
+	//#endregion
+	//#region ../packages/signals/src/lib/models/computed/computed.ts
+	/**
+	* A read-only Signal whose value is derived lazily from other Signals.
+	*
+	* The value is recomputed only when explicitly read and only if one or more
+	* of its (recursive) dependencies have changed since the last evaluation.
+	* The result is cached and reused until the Signal becomes stale again.
+	*
+	* @template T The type of the computed value.
+	*
+	* @see Signal algorithms — "The Signal.Computed class"
+	*/
+	var Computed = class Computed {
+		/**
+		* The current value of the signal.
+		*
+		* Uninitialised (`!`) until the first evaluation. After that, holds either
+		* the return value of `#callback` or a boxed error
+		* `{ isError: true; value: Error }` if the last evaluation threw.
+		*
+		* @internalSlot
+		* @see Signal algorithms — "Signal.Computed internal slots"
+		*/
+		#value;
+		/**
+		* The current evaluation state of this Signal.
+		*
+		* - `~dirty~`     — value is known to be stale or has never been evaluated.
+		* - `~checked~`   — an indirect source changed; may or may not be stale.
+		* - `~computing~` — `#callback` is currently executing; guards against cycles.
+		* - `~clean~`     — cached value is up-to-date.
+		*
+		* @internalSlot
+		* @see Signal algorithms — "Signal.Computed State machine"
+		*/
+		#state;
+		/**
+		* The ordered set of Signals read during the last evaluation of
+		* `#callback`. Cleared and rebuilt on every re-evaluation so that
+		* conditional branches that are no longer taken stop being tracked.
+		*
+		* May contain both `State` and `Computed` instances.
+		*
+		* @internalSlot
+		* @see Signal algorithms — "Signal.Computed internal slots"
+		*/
+		#sources;
+		/**
+		* Returns a snapshot of the current sources set for introspection.
+		*
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @returns An array of `State` and `Computed` instances that this Signal depends on.
+		* @internal
+		*/
+		getSources(symbol) {
+			assertPrivateContext(symbol);
+			return [...this.#sources];
+		}
+		/**
+		* The set of Signals and Watchers that directly depend on this Signal.
+		*
+		* Populated only when this Signal is reachable from at least one active
+		* `Watcher`. An un-watched `Computed` has an empty sinks set, which allows
+		* it to be garbage-collected independently from the rest of the graph.
+		*
+		* @internalSlot
+		* @see Signal algorithms — "Signal.Computed internal slots"
+		* @see Method — `Signal.Computed.prototype.get` (NOTE on sinks)
+		*/
+		#sinks;
+		/**
+		* Returns a snapshot of the current sinks set for introspection.
+		*
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @returns An array of `Computed` and `Watcher` instances that depend on this Signal.
+		* @internal
+		*/
+		getSinks(symbol) {
+			assertPrivateContext(symbol);
+			return [...this.#sinks];
+		}
+		/**
+		* The equality function used to determine whether a newly computed value
+		* is meaningfully different from the previously cached one.
+		*
+		* Called as `equals.call(computed, oldValue, newValue)`. Returns `true` if
+		* the values are considered equal, in which case no downstream propagation
+		* occurs. Defaults to `Object.is` when not provided via options.
+		*
+		* If this function throws, the exception is cached as the Signal's value
+		* and the outcome is treated as `~dirty~`.
+		*
+		* @internalSlot
+		* @see Signal algorithms — "Signal.Computed internal slots"
+		* @see Algorithm — "Set Signal value"
+		*/
+		#equals;
+		/**
+		* The pure function that produces this Signal's value. Evaluated lazily
+		* whenever the Signal is read while in a `~dirty~` or `~checked~` state.
+		*
+		* Called with `this` bound to the `Computed` instance itself so that
+		* internal methods (e.g. `addSource`) are accessible if needed.
+		* Any exception thrown by this function is caught and cached.
+		*
+		* @internalSlot
+		* @see Signal algorithms — "Signal.Computed internal slots"
+		*/
+		#callback;
+		/**
+		* Creates a new `Computed` signal.
+		*
+		* The Signal starts in the `~dirty~` state with an uninitialised value, so
+		* `#callback` will be invoked on the first `get()`.
+		*
+		* @param cb - Pure function evaluated lazily to produce the value.
+		*   Receives the `Computed` instance as `this`.
+		* @param options - Optional configuration:
+		*   - `equals` — custom equality function; defaults to `Object.is`.
+		*
+		* @see Signal algorithms — "Signal.Computed Constructor"
+		*/
+		constructor(cb, options) {
+			this.#callback = cb;
+			this.#equals = options?.equals ?? Object.is;
+			this.#sources = /* @__PURE__ */ new Set();
+			this.#sinks = /* @__PURE__ */ new Set();
+			this.#state = "dirty";
+		}
+		/**
+		* Returns the current value of this Signal, re-evaluating `#callback` if
+		* the cached value may be stale.
+		*
+		* Registers this Signal as a source of any outer `Computed` currently
+		* being evaluated (automatic dependency tracking).
+		*
+		* If the state is `~dirty~` or `~checked~`, walks the source graph
+		* depth-first to find and recalculate the deepest stale `Computed` first,
+		* then re-checks upward until this Signal is `~clean~`.
+		*
+		* @returns The current computed value, or a boxed error object if the last
+		*   evaluation threw.
+		* @throws If `frozen` is `true`.
+		* @throws If the Signal is in the `~computing~` state (cyclic dependency).
+		*
+		* @see Signal algorithms — "Method: Signal.Computed.prototype.get"
+		*/
+		get() {
+			if (GLOBAL_STATE.frozen) throw new Error("Cannot get value of a Computed signal while the global state is frozen");
+			if (this.#state === "computing") throw new Error("Circular dependency detected while computing a Computed signal");
+			GLOBAL_STATE.computing?.addSource(this, PRIVATE);
+			if (this.#sinks.size === 0) this.#computeValue();
+			else if (this.#state === "dirty" || this.#state === "checked") while (this.#state === "dirty" || this.#state === "checked") this.#findDeepestStale().#computeValue();
+			return this.#value;
+		}
+		/**
+		* Registers a Signal as a source of this `Computed`, discovered during the
+		* execution of `#callback`.
+		*
+		* If this `Computed` is currently being watched (has at least one sink),
+		* the source is also informed of this Signal as a new sink, building the
+		* live push-notification chain upward.
+		*
+		* @param source - The Signal read during evaluation.
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @internal
+		*/
+		addSource(source, symbol) {
+			assertPrivateContext(symbol);
+			this.#sources.add(source);
+			source.addSink(this, PRIVATE);
+		}
+		/**
+		* Returns the current evaluation state of this Signal.
+		*
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @internal
+		* @see Signal algorithms — "Signal.Computed State machine"
+		*/
+		getState(symbol) {
+			assertPrivateContext(symbol);
+			return this.#state;
+		}
+		/**
+		* Transitions this Signal to a new evaluation state.
+		*
+		* Only valid transitions (as defined by the state machine) are allowed.
+		* Invalid transitions throw an error.
+		*
+		* @param newState - The target state.
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @throws If the transition from the current state to `newState` is not allowed.
+		* @internal
+		* @see Signal algorithms — "Signal.Computed State machine"
+		*/
+		setState(newState, symbol) {
+			assertPrivateContext(symbol);
+			if (this.#state === newState) return;
+			if (!this.#isValidTransition(this.#state, newState)) {
+				if (isDevMode()) {
+					console.warn(`Invalid state transition from ${this.#state} to ${newState} in Computed Signal`);
+					console.warn((/* @__PURE__ */ new Error()).stack);
+				}
+				return;
+			}
+			this.#state = newState;
+			if (this.#state === "dirty" || this.#state === "checked") for (const sink of this.#sinks) sink instanceof Computed ? sink.setState("checked", PRIVATE) : sink.notify(PRIVATE);
+		}
+		/**
+		* Registers a new sink (a `Computed` or `Watcher` that directly depends on
+		* this Signal) in the internal sinks set.
+		*
+		* If this is the first sink, propagates the sink registration recursively
+		* up through `#sources`, building the live dependency chain that enables
+		* push-based invalidation.
+		*
+		* @param sink - The dependent node to register.
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @internal
+		*/
+		addSink(sink, symbol) {
+			assertPrivateContext(symbol);
+			if (this.#sinks.size === 0) for (const source of this.#sources) source.addSink(this, PRIVATE);
+			this.#sinks.add(sink);
+		}
+		/**
+		* Removes a sink from the internal sinks set.
+		*
+		* If the sinks set becomes empty after removal, propagates the removal
+		* recursively up through `#sources`, tearing down the live dependency
+		* chain and allowing garbage collection of un-watched nodes.
+		*
+		* @param sink - The dependent node to remove.
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @internal
+		*/
+		removeSink(sink, symbol) {
+			assertPrivateContext(symbol);
+			this.#sinks.delete(sink);
+			if (this.#sinks.size === 0) for (const source of this.#sources) source.removeSink(this, PRIVATE);
+		}
+		/**
+		* Recursively walks the source graph depth-first to find the deepest,
+		* left-most `Computed` node that is in a `~dirty~` or `~checked~` state.
+		*
+		* This ensures that recalculation always starts from the bottom of the
+		* dependency graph, so every node sees already-updated dependencies —
+		* the core of glitch-free evaluation.
+		*
+		* Cuts off the search when hitting a `~clean~` `Computed` source, since
+		* its subtree is guaranteed to be up-to-date.
+		*
+		* @returns The deepest stale `Computed` found, or `node` itself if none of
+		*   its sources are stale.
+		*/
+		#findDeepestStale() {
+			const unclearNode = [...this.#sources].find((source) => source instanceof Computed && (source.#state === "dirty" || source.#state === "checked"));
+			return unclearNode ? unclearNode.#findDeepestStale() : this;
+		}
+		/**
+		* Executes `#callback` to recompute this Signal's value.
+		*
+		* Implements the "recalculate dirty computed Signal" algorithm:
+		* 1. Clears stale sources and removes this Signal from their sinks.
+		* 2. Sets `computing` to this Signal for automatic dependency tracking.
+		* 3. Runs the callback, caching the return value or any thrown exception.
+		* 4. Restores the previous `computing` value.
+		* 5. Runs the "set Signal value" algorithm to detect value changes.
+		* 6. Transitions state to `~clean~`.
+		* 7. Propagates `~dirty~` to sinks (or attempts `~clean~` if value unchanged).
+		*
+		* @see Signal algorithms — "Algorithm: recalculate dirty computed Signal"
+		*/
+		#computeValue() {
+			for (const source of this.#sources) source.removeSink(this, PRIVATE);
+			this.#sources.clear();
+			pushComputed(this);
+			this.setState("computing", PRIVATE);
+			let newValue;
+			try {
+				newValue = this.#callback.call(this);
+			} catch (error) {
+				if (isDevMode()) console.error("Error thrown while computing a Computed signal:", error);
+				newValue = {
+					isError: true,
+					value: error
+				};
+			} finally {
+				popComputed();
+			}
+			const outcome = this.#setValue(newValue);
+			this.setState("clean", PRIVATE);
+			if (outcome === "dirty") for (const sink of this.#sinks) sink instanceof Computed ? sink.setState("dirty", PRIVATE) : sink.notify(PRIVATE);
+			else this.#propagateClean();
+		}
+		/**
+		* Implements the "set Signal value" algorithm.
+		*
+		* Compares the new value against the cached one using `#equals`. If equal,
+		* returns `~clean~` and leaves `#value` untouched. Otherwise updates
+		* `#value` and returns `~dirty~`.
+		*
+		* Special cases:
+		* - If `newValue` is a boxed error, `#equals` is skipped and the error is
+		*   cached directly.
+		* - If `#equals` itself throws, the exception is cached as a boxed error
+		*   and the outcome is `~dirty~`.
+		*
+		* @param newValue - The value (or boxed error) produced by `#callback`.
+		* @returns `~clean~` if the value is unchanged, `~dirty~` otherwise.
+		*
+		* @see Signal algorithms — "Set Signal value algorithm"
+		*/
+		#setValue(newValue) {
+			const oldValue = this.#value;
+			if (this.#isErrorValue(newValue)) {
+				this.#value = newValue;
+				return "dirty";
+			}
+			try {
+				if (!this.#isErrorValue(oldValue) && this.#equals.call(this, oldValue, newValue)) return "clean";
+			} catch (equalsError) {
+				this.#value = {
+					isError: true,
+					value: equalsError
+				};
+				return "dirty";
+			}
+			this.#value = newValue;
+			return "dirty";
+		}
+		/**
+		* Recursively marks `~checked~` sinks as `~clean~` when all of their
+		* immediate sources are already `~clean~`.
+		*
+		* Called after a recalculation that produced an unchanged value (`~clean~`
+		* outcome from `#setValue`). Propagates the clean signal upward through
+		* the graph so that Computed nodes that were only transitively dirty — and
+		* whose dependencies have not actually changed — are not needlessly
+		* re-evaluated on the next read.
+		*
+		* @see Signal algorithms — "Algorithm: recalculate dirty computed Signal"
+		*/
+		#propagateClean() {
+			for (const sink of this.#sinks) if (sink instanceof Computed && sink.#state === "checked") {
+				let allSourcesClean = true;
+				for (const source of sink.#sources) if (source instanceof Computed && source.#state !== "clean") {
+					allSourcesClean = false;
+					break;
+				}
+				if (allSourcesClean) {
+					sink.#state = "clean";
+					sink.#propagateClean();
+				}
+			}
+		}
+		/**
+		* Type guard that checks whether a value is a boxed error object.
+		*
+		* Used to distinguish a legitimately computed value from a cached
+		* exception produced by `#callback` or `#equals`.
+		*
+		* @param value - The value to inspect.
+		* @returns `true` if `value` is `{ isError: true; value: Error }`.
+		*/
+		#isErrorValue(value) {
+			return typeof value === "object" && !!value && "isError" in value;
+		}
+		#isValidTransition(from, to) {
+			switch (from) {
+				case "checked": return to === "clean" || to === "dirty";
+				case "clean": return to === "checked" || to === "dirty";
+				case "dirty": return to === "computing";
+				case "computing": return to === "clean";
+			}
+		}
+	};
+	//#endregion
+	//#region ../packages/signals/src/lib/models/state/state.ts
+	var State = class {
+		/**
+		* The current value of the signal.
+		*
+		* Initialised to `initialValue` in the constructor and updated by `set`
+		* whenever the new value is not equal to the current one according to
+		* `#equals`.
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.State internal slots'
+		*/
+		#value;
+		/**
+		* The equality function used to determine whether a new value is
+		* meaningfully different from the current one.
+		*
+		* Called as `equals.call(signal, oldValue, newValue)`. If it returns
+		* `true` the signal is considered unchanged and no propagation occurs.
+		* Defaults to `Object.is` when not provided via options.
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.State internal slots'
+		* @see Algorithm — 'Set Signal value'
+		*/
+		#equals;
+		/**
+		* Optional callback invoked (with `frozen = true`) the first time this
+		* Signal gains a sink — i.e. when it transitions from un-observed to
+		* observed by at least one `Watcher` (directly or transitively).
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.State internal slots'
+		* @see Method — `Signal.subtle.Watcher.prototype.watch`
+		*/
+		#watched;
+		/**
+		* Optional callback invoked (with `frozen = true`) when this Signal loses
+		* its last sink — i.e. when it transitions from observed back to
+		* un-observed.
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.State internal slots'
+		* @see Method — `Signal.subtle.Watcher.prototype.unwatch`
+		*/
+		#unwatched;
+		/**
+		* The set of watched signals that directly depend on this one.
+		*
+		* Populated only when this Signal is reachable from at least one active
+		* `Watcher` — un-watched Signals have an empty sinks set, which allows
+		* them to be garbage-collected independently from the rest of the graph.
+		*
+		* Should contain both `Computed` and `Watcher` instances, as both can be
+		* direct dependents of a `State`.
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.State internal slots'
+		* @see Method — `Signal.State.prototype.get` (NOTE on sinks)
+		*/
+		#sinks;
+		/**
+		* Returns a snapshot of the current sinks set for introspection.
+		*
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @returns An array of `Computed` and `Watcher` instances that depend on this Signal.
+		* @internal
+		*/
+		getSinks(symbol) {
+			assertPrivateContext(symbol);
+			return [...this.#sinks];
+		}
+		/**
+		* Creates a new `State` signal.
+		*
+		* @param initialValue - The initial value of the signal.
+		* @param options - Optional configuration:
+		*   - `equals` — custom equality function; defaults to `Object.is`.
+		*   - `watched` — called when the signal gains its first sink.
+		*   - `unwatched` — called when the signal loses its last sink.
+		*
+		* @see Signal algorithms — 'Constructor: Signal.State(initialValue, options)'
+		*/
+		constructor(initialValue, options) {
+			this.#value = initialValue;
+			this.#equals = options?.equals ?? Object.is;
+			this.#watched = options?.watched;
+			this.#unwatched = options?.unwatched;
+			this.#sinks = /* @__PURE__ */ new Set();
+		}
+		/**
+		* Returns the current value of the signal, registering this Signal as a
+		* source of the innermost `Computed` currently being evaluated (if any).
+		*
+		* @throws If `frozen` is `true` — reads are forbidden while a protected
+		* callback (`notify`, `watched`, `unwatched`) is executing.
+		*
+		* @see Signal algorithms — 'Method: Signal.State.prototype.get()'
+		*/
+		get() {
+			if (GLOBAL_STATE.frozen) throw new Error("Cannot get value while signals are frozen");
+			GLOBAL_STATE.computing?.addSource(this, PRIVATE);
+			return this.#value;
+		}
+		/**
+		* Updates the signal's value and propagates changes to all dependent
+		* sinks.
+		*
+		* If `equals(currentValue, newValue)` returns `true` the call is a no-op
+		* and no propagation occurs. Otherwise `#value` is updated, all direct
+		* `Computed` sinks are marked `~dirty~`, indirect ones `~checked~`, and
+		* each reachable `Watcher` has its `notify` callback invoked synchronously
+		* (with `frozen = true`).
+		*
+		* @param newValue - The new value to set.
+		* @throws If `frozen` is `true` — writes are forbidden while a protected
+		* callback is executing.
+		*
+		* @see Signal algorithms — 'Method: Signal.State.prototype.set(newValue)'
+		* @see Algorithm — 'Set Signal value'
+		*/
+		set(newValue) {
+			if (GLOBAL_STATE.frozen) throw new Error("Cannot set value while signals are frozen");
+			if (!this.#equals.call(this, this.#value, newValue)) {
+				this.#value = newValue;
+				for (const sink of this.#sinks) sink instanceof Computed ? sink.setState("dirty", PRIVATE) : sink.notify(PRIVATE);
+			}
+		}
+		/**
+		* Registers a new sink (a `Computed` or `Watcher` that depends on this
+		* Signal) in the internal sinks set.
+		*
+		* Called by `Watcher.prototype.watch` when building the live dependency
+		* chain, and by `Computed` when propagating sink registration up through
+		* its sources.
+		*
+		* @param sink - The dependent node to register.
+		* @param symbol - The private symbol for validation.
+		* @internal
+		*/
+		addSink(sink, symbol) {
+			assertPrivateContext(symbol);
+			const empty = this.#sinks.size === 0;
+			this.#sinks.add(sink);
+			if (empty && this.#watched) {
+				GLOBAL_STATE.frozen = true;
+				try {
+					this.#watched();
+				} catch (error) {
+					if (isDevMode()) console.error("Error thrown while running a State Signal watched callback:", error);
+					throw error;
+				} finally {
+					GLOBAL_STATE.frozen = false;
+				}
+			}
+		}
+		/**
+		* Removes a sink from the internal sinks set.
+		*
+		* Called by `Watcher.prototype.unwatch` when tearing down the live
+		* dependency chain. If the sinks set becomes empty after removal, the
+		* caller is responsible for propagating the removal up through this
+		* Signal's sources.
+		*
+		* @param sink - The dependent node to remove.
+		* @param symbol - The private symbol for validation.
+		* @internal
+		*/
+		removeSink(sink, symbol) {
+			assertPrivateContext(symbol);
+			this.#sinks.delete(sink);
+			if (this.#sinks.size === 0 && this.#unwatched) {
+				GLOBAL_STATE.frozen = true;
+				try {
+					this.#unwatched();
+				} catch (error) {
+					if (isDevMode()) console.error("Error thrown while running a State Signal unwatched callback:", error);
+					throw error;
+				} finally {
+					GLOBAL_STATE.frozen = false;
+				}
+			}
+		}
+	};
+	//#endregion
+	//#region ../packages/signals/src/lib/models/watcher/watcher.ts
+	/**
+	* A `Watcher` observes a set of Signals and fires a `notify` callback
+	* synchronously when any of their (recursive) dependencies change.
+	*
+	* It is the low-level primitive on top of which frameworks implement
+	* effects and scheduling. It does not hold a value and has no generic
+	* type parameter.
+	*
+	* @see Signal algorithms — 'The `Signal.subtle.Watcher` class'
+	*/
+	var Watcher = class {
+		/**
+		* The current state of the Watcher.
+		*
+		* - `~waiting~`  — newly created, or `notify` has already been called since
+		*                  the last `watch` call. Not actively observing changes.
+		* - `~watching~` — actively watching; no dependency has changed yet.
+		* - `~pending~`  — a dependency has changed but `notify` has not yet run.
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.subtle.Watcher State machine'
+		*/
+		#state;
+		/**
+		* The ordered set of Signals this Watcher is currently watching.
+		* May contain both `State` and `Computed` instances.
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.subtle.Watcher internal slots'
+		*/
+		#signals;
+		/**
+		* Returns a snapshot of the current watched signals set for introspection.
+		*
+		* @param symbol - Private access symbol; rejects calls from outside the library.
+		* @returns An array of `State` and `Computed` instances that this Watcher is watching.
+		* @internal
+		*/
+		getSources(symbol) {
+			assertPrivateContext(symbol);
+			return [...this.#signals];
+		}
+		/**
+		* The callback invoked synchronously when a watched Signal (or one of its
+		* recursive dependencies) changes for the first time since the last
+		* `watch` call.
+		*
+		* Receives the Watcher itself as `this`. No Signals may be read or written
+		* during its execution (`frozen` is `true` for its entire duration).
+		*
+		* @internalSlot
+		* @see Signal algorithms — 'Signal.subtle.Watcher internal slots'
+		*/
+		#notifyCallback;
+		/**
+		* Creates a new Watcher.
+		*
+		* The Watcher starts in the `~waiting~` state with an empty signals set.
+		*
+		* @param notifyCallback - Called synchronously (with `frozen = true`) the
+		* first time a watched dependency changes after each `watch` call. No
+		* Signals may be read or written inside this callback.
+		*
+		* @see Signal algorithms — 'Constructor: new Signal.subtle.Watcher(callback)'
+		*/
+		constructor(notifyCallback) {
+			this.#state = "waiting";
+			this.#signals = /* @__PURE__ */ new Set();
+			this.#notifyCallback = notifyCallback;
+		}
+		/**
+		* Returns the subset of watched Signals that are `Computed` instances
+		* currently in a `~dirty~` or `~checked~` state, meaning they may have a
+		* stale value that has not yet been re-evaluated.
+		*
+		* Typically called inside the microtask scheduled by the `notify` callback
+		* to know which Signals need to be pulled.
+		*
+		* @returns An array of `Computed` signals that are dirty or checked.
+		*
+		* @see Signal algorithms — 'Method: Signal.subtle.Watcher.prototype.getPending()'
+		*/
+		getPending() {
+			const filteredSignals = new Array();
+			for (const signal of this.#signals) {
+				if (!(signal instanceof Computed)) continue;
+				const state = signal.getState(PRIVATE);
+				if (state === "dirty" || state === "checked") filteredSignals.push(signal);
+			}
+			return filteredSignals;
+		}
+		/**
+		* Adds the given Signals to the watched set and transitions the Watcher to
+		* the `~watching~` state.
+		*
+		* For each newly-watched Signal, the Watcher is registered as a sink and —
+		* if it is the first sink — the sink registration is propagated recursively
+		* up through the Signal's sources, building the live dependency chain.
+		*
+		* The `watched` callback of each Signal (if any) is called with
+		* `frozen = true`.
+		*
+		* @param signals - One or more `State` signals to start watching.
+		* @throws If `frozen` is `true` at the time of the call.
+		*
+		* @see Signal algorithms — 'Method: Signal.subtle.Watcher.prototype.watch(...signals)'
+		*/
+		watch(...signals) {
+			if (GLOBAL_STATE.frozen) throw new Error("Cannot watch signals while frozen");
+			for (let i = 0; i < signals.length; i++) {
+				const signal = signals[i];
+				if (this.#signals.has(signal)) throw new Error("Cannot watch a signal that is already being watched");
+				this.#signals.add(signal);
+				signal.addSink(this, PRIVATE);
+			}
+			this.setState("watching", PRIVATE);
+		}
+		/**
+		* Removes the given Signals from the watched set.
+		*
+		* For each removed Signal, the Watcher is unregistered as a sink. If the
+		* Signal's sink set becomes empty as a result, the removal is propagated
+		* recursively up through its sources, tearing down the live dependency
+		* chain and allowing garbage collection of unwatched nodes.
+		*
+		* The `unwatched` callback of each Signal (if any) is called with
+		* `frozen = true`.
+		*
+		* If no Signals remain in the watched set, the Watcher transitions back to
+		* the `~waiting~` state.
+		*
+		* @param signals - One or more `State` signals to stop watching.
+		* @throws If `frozen` is `true` at the time of the call.
+		* @throws If any of the given Signals is not currently being watched.
+		*
+		* @see Signal algorithms — 'Method: Signal.subtle.Watcher.prototype.unwatch(...signals)'
+		*/
+		unwatch(...signals) {
+			if (GLOBAL_STATE.frozen) throw new Error("Cannot unwatch signals while frozen");
+			for (let i = 0; i < signals.length; i++) {
+				const signal = signals[i];
+				if (!this.#signals.has(signal)) throw new Error("Cannot unwatch a signal that is not being watched");
+				this.#signals.delete(signal);
+				signal.removeSink(this, PRIVATE);
+			}
+			if (!this.#signals.size) this.setState("waiting", PRIVATE);
+		}
+		/**
+		* Get the current state of the Watcher.
+		* @param symbol - The private symbol for prevent external calls.
+		*/
+		getState(symbol) {
+			assertPrivateContext(symbol);
+			return this.#state;
+		}
+		/**
+		* Set the current state of the Watcher.
+		* @param newState - The new state to set.
+		* @param symbol - The private symbol for prevent external calls.
+		* @throws If the transition from `pending` to `watching` is attempted.
+		*/
+		setState(newState, symbol) {
+			assertPrivateContext(symbol);
+			if (this.#state === newState) return;
+			if (!this.#isValidTransition(this.#state, newState)) {
+				if (isDevMode()) {
+					console.warn(`Invalid state transition from ${this.#state} to ${newState} in Watcher`);
+					console.warn((/* @__PURE__ */ new Error()).stack);
+				}
+				return;
+			}
+			this.#state = newState;
+		}
+		/**
+		* Invoce the notify callback when a watched dependency changes
+		* @param symbol - The private symbol for prevent external calls.
+		*/
+		notify(symbol) {
+			assertPrivateContext(symbol);
+			GLOBAL_STATE.frozen = true;
+			try {
+				this.setState("pending", PRIVATE);
+				this.#notifyCallback.call(this);
+			} catch (error) {
+				if (isDevMode()) console.error("Error thrown while running a Watcher notify callback:", error);
+				throw error;
+			} finally {
+				this.setState("waiting", PRIVATE);
+				GLOBAL_STATE.frozen = false;
+			}
+		}
+		#isValidTransition(from, to) {
+			switch (from) {
+				case "waiting": return to === "watching";
+				case "watching": return to === "pending" || to === "waiting";
+				case "pending": return to === "waiting";
+			}
+		}
+	};
+	//#endregion
+	//#region ../packages/signals/src/lib/subtle.ts
+	/**
+	* Executes a function without tracking any dependencies.
+	* @param fn - The function to execute without tracking.
+	* @returns The result of the function execution.
+	*/
+	function untrack(fn) {
+		const prevComputing = GLOBAL_STATE.computing;
+		GLOBAL_STATE.computing = null;
+		try {
+			return fn();
+		} catch (error) {
+			if (isDevMode()) console.error("Error thrown while running an Untracked signal:", error);
+			throw error;
+		} finally {
+			GLOBAL_STATE.computing = prevComputing;
+		}
+	}
+	/**
+	* Returns the currently active `Computed` instance being evaluated, or `null`
+	* @returns The currently active `Computed` instance, or `null` if none is being evaluated.
+	*/
+	function currentComputed() {
+		return GLOBAL_STATE.computing;
+	}
+	/**
+	* Returns the ordered list of all Signals which the given `Computed` or
+	* `Watcher` referenced during its last evaluation.
+	*
+	* - For a `Computed`, these are the Signals read inside its callback.
+	* - For a `Watcher`, these are the Signals it is currently watching.
+	*
+	* @param signal - The `Computed` or `Watcher` to introspect.
+	* @returns An array of `State` and `Computed` instances.
+	*/
+	function introspectSources(signal) {
+		return signal.getSources(PRIVATE);
+	}
+	/**
+	* Returns the direct dependents of the given Signal — Watchers that contain
+	* it, plus any `Computed` Signals which read it during their last evaluation
+	* (if that `Computed` is recursively watched).
+	*
+	* @param signal - The `State` or `Computed` Signal to introspect.
+	* @returns An array of `Computed` and `Watcher` instances.
+	*/
+	function introspectSinks(signal) {
+		return signal.getSinks(PRIVATE);
+	}
+	/**
+	* Returns `true` if the given Signal is 'live' — i.e. it is watched by a
+	* `Watcher`, or it is read by a `Computed` Signal which is (recursively)
+	* live.
+	*
+	* @param signal - The `State` or `Computed` Signal to check.
+	* @returns `true` if the Signal has at least one sink.
+	*/
+	function hasSinks(signal) {
+		return signal.getSinks(PRIVATE).length > 0;
+	}
+	/**
+	* Returns `true` if the given node is 'reactive' — i.e. it depends on some
+	* other Signal. A `Computed` where `hasSources` is `false` will always
+	* return the same constant.
+	*
+	* @param signal - The `Computed` or `Watcher` to check.
+	* @returns `true` if the node has at least one source.
+	*/
+	function hasSources(signal) {
+		return signal.getSources(PRIVATE).length > 0;
+	}
+	//#endregion
+	//#region ../packages/signals/src/lib/load-signals.ts
+	/**
+	* Loads the Signals library by defining the `Signal` global object with the following properties:
+	* - `State`: The `State` class for creating reactive state variables.
+	* - `Computed`: The `Computed` class for creating derived reactive values.
+	* - `Watcher`: The `Watcher` class for observing changes in signals.
+	* - `subtle`: An object containing internal utility functions for working with signals, including:
+	*  - `untrack`: Executes a function without tracking dependencies.
+	*  - `currentComputed`: Returns the currently active `Computed` instance being evaluated, or `null` if none.
+	*  - `introspectSources`: Returns the list of sources for a given `Computed` or `Watcher`.
+	*  - `introspectSinks`: Returns the list of sinks for a given `State` or `Computed`.
+	*  - `hasSinks`: Returns `true` if a given `State` or `Computed` has at least one sink.
+	*  - `hasSources`: Returns `true` if a given `Computed` or `Watcher` has at least one source.
+	*  - `Watcher`: The `Watcher` class for observing changes in signals.
+	* 
+	* This function should be called once to initialize the Signals library and make its API available globally.
+	*
+	* @param options - Optional configuration object.
+	* @param options.devMode - When `true`, enables development mode with extra runtime checks and logging.
+	*/
+	function loadSignals(options) {
+		setDevMode(options?.devMode ?? false);
+		globalThis.Signal ??= {
+			State,
+			Computed,
+			subtle: {
+				untrack,
+				currentComputed,
+				introspectSources,
+				introspectSinks,
+				hasSinks,
+				hasSources,
+				Watcher
+			}
+		};
+	}
+	//#endregion
+	exports.loadSignals = loadSignals;
+});