@xaendar/signals 0.0.1

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@xaendar/signals",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "Kaitenjo",
+  "license": "MIT",
+  "description": "A library for managing signals in web applications",
+  "peerDependencies": {
+    "@xaendar/common": "^1.0.0",
+    "vite": "^8.0.4"
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,180 @@
+declare global {
+  namespace Signal {
+    /**
+     * A mutable Signal that holds a value and notifies dependents when it changes.
+     *
+     * @template T The type of the value held by this Signal.
+     */
+    class State <T = any> {
+      /**
+       * 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.
+       */
+      constructor(value: T, options?: { equals?: (a: T, b: T) => boolean, watched?: () => void, unwatched?: () => void });
+      /**
+       * 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.
+       */
+      get(): T;
+      /**
+       * 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 the 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.
+       */
+      set(newValue: T): void;
+    }
+
+    /**
+     * 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.
+     */
+    class Computed<T = any> {
+      /**
+       * Creates a new `Computed` signal.
+       *
+       * The Signal starts in the dirty state with an uninitialised value, so
+       * the callback will be invoked on the first `get()`.
+       *
+       * @param computeFn - Pure function evaluated lazily to produce the value.
+       * @param options - Optional configuration:
+       *   - `equals` — custom equality function; defaults to `Object.is`.
+       */
+      constructor(computeFn: () => T, options?: { equals?: (a: T, b: T) => boolean, watched?: () => void, unwatched?: () => void });
+      /**
+       * Returns the current value of this Signal, re-evaluating the callback if
+       * the cached value may be stale.
+       *
+       * Registers this Signal as a source of any outer `Computed` currently
+       * being evaluated (automatic dependency tracking).
+       *
+       * @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).
+       */
+      get(): T | { isError: true, value: Error };
+    }
+
+    namespace subtle {
+      /**
+       * Executes a function without tracking any dependencies.
+       * @param fn - The function to execute without tracking.
+       * @returns The result of the function execution.
+       */
+      function untrack<T>(fn: () => T): T;
+      /**
+       * 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(): Computed | null;
+      /**
+       * 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 s - The `Computed` or `Watcher` to introspect.
+       * @returns An array of `State` and `Computed` instances.
+       */
+      function introspectSources(s: Computed | Watcher): (State | Computed)[];
+      /**
+       * 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: State | Computed): (Computed | Watcher)[];
+      /**
+       * 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: State | Computed): boolean;
+      /**
+       * 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 s - The `Computed` or `Watcher` to check.
+       * @returns `true` if the node has at least one source.
+       */
+      function hasSources(s: Computed | Watcher): boolean;
+
+      /**
+       * 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.
+       */
+      class Watcher {
+        /**
+         * Creates a new Watcher.
+         *
+         * The Watcher starts in the waiting state with an empty signals set.
+         *
+         * @param notify - 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.
+         */
+        constructor(notify: () => void);
+        /**
+         * 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.
+         *
+         * @param signals - One or more Signals to start watching.
+         * @throws If `frozen` is `true` at the time of the call.
+         */
+        watch(...signals: (State | Computed)[]): void;
+        /**
+         * 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.
+         *
+         * @param signals - One or more 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.
+         */
+        unwatch(...signals: (State | Computed)[]): void;
+      }
+    }
+  }
+}
+
+export {};

package/src/lib/globals.ts

@@ -0,0 +1,45 @@
+import { Stack } from '@xaendar/common';
+import { Computed } from './models/computed';
+import { GlobalState } from './types/global-state.type';
+
+/**
+ * Global state for the signals runtime.
+ * Tracks the currently computing `Computed` instance, whether the state is frozen,
+ * and the current generation counter.
+ *
+ * @internal
+ */
+export const GLOBAL_STATE: GlobalState = {
+  computing: null,
+  frozen: false
+};
+
+const computingStack = new Stack<Computed>;
+
+/**
+ * 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
+ */
+export function pushComputed(computed: Computed): void {
+  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
+ */
+export function popComputed(): void {
+  computingStack.pop();
+  GLOBAL_STATE.computing = computingStack[computingStack.length - 1] ?? null;
+}

package/src/lib/load-signals.ts

@@ -0,0 +1,36 @@
+import { Computed } from './models/computed';
+import { State } from './models/state';
+import { Watcher } from './models/watcher';
+import { currentComputed, hasSinks, hasSources, introspectSinks, introspectSources, untrack } from './subtle';
+
+/**
+ * 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.
+ */
+export function loadSignals(): void {
+  globalThis.Signal ??= {
+    State,
+    Computed,
+    subtle: {
+      untrack,
+      currentComputed,
+      introspectSources: introspectSources as unknown as typeof Signal.subtle.introspectSources,
+      introspectSinks: introspectSinks as unknown as typeof Signal.subtle.introspectSinks,
+      hasSinks: hasSinks as unknown as typeof Signal.subtle.hasSinks,
+      hasSources: hasSources as unknown as typeof Signal.subtle.hasSources,
+      Watcher
+    }
+  }
+}

package/src/lib/models/computed.ts

@@ -0,0 +1,421 @@
+
+import { GLOBAL_STATE, pushComputed, popComputed } from '../globals';
+import { PRIVATE, assertPrivateContext } from '../private-symbol';
+import { ComputedState } from '../types/computed-state.type';
+import { SignalEqual } from '../types/signal-equal.type';
+import { SignalOptions } from '../types/signal-options.type';
+import { State } from './state';
+import { Watcher } from './watcher';
+
+/**
+ * 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"
+ */
+export class Computed<T = any> {
+  /**
+   * 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!: T | { isError: true; value: Error };
+  /**
+   * 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: ComputedState;
+  /**
+   * 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: Set<State<unknown> | Computed<unknown>>;
+  /**
+ * 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
+ */
+  public getSources(symbol: symbol): (State<unknown> | Computed<unknown>)[] {
+    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: Set<Computed<unknown> | Watcher>;
+  /**
+   * 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
+   */
+  public getSinks(symbol: symbol): (Computed<unknown> | Watcher)[] {
+    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: SignalEqual<T>;
+  /**
+   * 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: (this: Computed<T>) => T;
+
+  /**
+   * 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: (this: Computed<T>) => T, options?: SignalOptions<T>) {
+    this.#callback = cb;
+    this.#equals = options?.equals ?? Object.is;
+    this.#sources = new Set;
+    this.#sinks = 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"
+   */
+  public get(): T | { isError: true; value: Error } {
+    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') {
+        const deepest = this.#findDeepestStale();
+        deepest.#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
+   */
+  public addSource(source: State | Computed, symbol: 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"
+   */
+  public getState(symbol: symbol): ComputedState {
+    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"
+   */
+  public setState(newState: ComputedState, symbol: symbol): void {
+    assertPrivateContext(symbol);
+
+    if (this.#state !== newState && this.#isValidTransition(this.#state, newState)) {
+      this.#state = newState;
+    }
+  }
+
+  /**
+   * 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
+   */
+  public addSink(sink: Computed<unknown> | Watcher, symbol: symbol) {
+    assertPrivateContext(symbol);
+    if (this.#sinks.size === 0) {
+      this.#sources.forEach(source => 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
+   */
+  public removeSink(sink: Computed | Watcher, symbol: symbol) {
+    assertPrivateContext(symbol);
+    this.#sinks.delete(sink);
+
+    if (this.#sinks.size === 0) {
+      this.#sources.forEach(source => 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(): Computed {
+    const unclearNode = [...this.#sources].find((source): source is Computed => 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(): void {
+    this.#sources.forEach(source => source.removeSink(this, PRIVATE));
+    this.#sources.clear();
+
+    pushComputed(this);
+    this.#state = 'computing';
+
+    let newValue: T | { isError: true; value: Error };
+
+    try {
+      newValue = this.#callback.call(this);
+    } catch (error) {
+      newValue = { isError: true, value: error as Error };
+    } finally {
+      popComputed();
+    }
+
+    const outcome = this.#setValue(newValue);
+
+    outcome === 'dirty'
+      ? this.#sinks.forEach(sink => sink instanceof Computed ? sink.setState('dirty', PRIVATE) : sink.notify(PRIVATE))
+      : this.#propagateClean();
+
+    this.#state = 'clean';
+  }
+
+  /**
+   * 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: T | { isError: true; value: Error }): 'clean' | 'dirty' {
+    const oldValue = this.#value;
+
+    /*
+      If new value is an error we always update without calling equals
+    */
+    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 as Error };
+      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(): void {
+    [...this.#sinks]
+      .filter((sink): sink is Computed<unknown> => sink instanceof Computed && sink.#state === 'checked')
+      .forEach(sink => {
+        const allSourcesClean = [...sink.#sources].every(source => !(source instanceof Computed) || source.#state === 'clean');
+        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: unknown): value is { isError: true; value: Error } {
+    return typeof value === 'object' && !!value && 'isError' in value;
+  }
+
+  #isValidTransition(from: ComputedState, to: ComputedState): boolean {
+    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';
+    }
+  }
+}

package/src/lib/models/state.ts

@@ -0,0 +1,208 @@
+import { NoArgsVoidFunction } from '@xaendar/common';
+import { GLOBAL_STATE } from '../globals';
+import { PRIVATE, assertPrivateContext } from '../private-symbol';
+import { SignalEqual } from '../types/signal-equal.type';
+import { SignalOptions } from '../types/signal-options.type';
+import { Computed } from './computed';
+import { Watcher } from './watcher';
+
+export class State<T = any> {
+  /**
+   * 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: T;
+  /**
+   * 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: SignalEqual<T>
+  /**
+   * 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?: NoArgsVoidFunction;
+  /**
+   * 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?: NoArgsVoidFunction;
+  /**
+   * 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: Set<Computed<unknown> | Watcher>;
+  /**
+   * 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
+   */
+  public getSinks(symbol: symbol): (Computed<unknown> | Watcher)[] {
+    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: T, options?: SignalOptions<T>) {
+    this.#value = initialValue;
+    this.#equals = options?.equals ?? Object.is;
+    this.#watched = options?.watched;
+    this.#unwatched = options?.unwatched;
+    this.#sinks = 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()'
+   */
+  public get(): T {
+    if (GLOBAL_STATE.frozen) {
+      throw new Error('Cannot get value while signals are frozen');
+    }
+
+    /*
+      If there is a currently computing `Computed`, register this `State` as a
+      source of that `Computed`. 
+      This is how the dependency graph is built.
+
+      THis is done every time a `State` is read to guarantee always up-to-date 
+      tracking of dependencies, even if they change between computations
+    */
+    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'
+   */
+  public set(newValue: T): void {
+    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;
+      this.#sinks.forEach(sink => 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
+   */
+  public addSink(sink: Computed | Watcher, symbol: symbol): void {
+    assertPrivateContext(symbol);
+    const empty = this.#sinks.size === 0;
+    this.#sinks.add(sink);
+
+    if (empty && this.#watched) {
+      GLOBAL_STATE.frozen = true;
+      try {
+        this.#watched();
+      } 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
+   */
+  public removeSink(sink: Computed | Watcher, symbol: symbol): void {
+    assertPrivateContext(symbol);
+    this.#sinks.delete(sink);
+    const empty = this.#sinks.size === 0;
+
+    if (empty && this.#unwatched) {
+      GLOBAL_STATE.frozen = true;
+      try {
+        this.#unwatched();
+      } finally {
+        GLOBAL_STATE.frozen = false;
+      }
+    }
+  }
+}

package/src/lib/models/watcher.ts

@@ -0,0 +1,229 @@
+import { NoArgsVoidFunction } from '@xaendar/common';
+import { GLOBAL_STATE } from '../globals';
+import { PRIVATE, assertPrivateContext } from '../private-symbol';
+import { WatcherState } from '../types/watcher-state.type';
+import { Computed } from './computed';
+import { State } from './state';
+
+/**
+ * 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'
+ */
+export class Watcher {
+  /**
+   * 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: WatcherState;
+  /**
+   * 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: Set<State<unknown> | Computed<unknown>>;
+  /**
+   * 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
+   */
+  public getSources(symbol: symbol): (State<unknown> | Computed<unknown>)[] {
+    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: NoArgsVoidFunction;
+
+  /**
+   * 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: NoArgsVoidFunction) {
+    this.#state = 'waiting';
+    this.#signals = 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()'
+   */
+  public getPending(): Computed<unknown>[] {
+    return [...this.#signals].filter((signal): signal is Computed<unknown> => {
+      if (!(signal instanceof Computed)) {
+        return false;
+      }
+
+      const state = signal.getState(PRIVATE);
+      return state === 'dirty' || state === 'checked';
+    });
+  }
+
+  /**
+   * 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)'
+   */
+  public watch(...signals: (State | Computed)[]) {
+    if (GLOBAL_STATE.frozen) {
+      throw new Error('Cannot watch signals while frozen');
+    }
+
+    signals.forEach(signal => {
+      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);
+    });
+
+
+    if (this.#state === 'waiting') {
+      this.#state = 'watching';
+    }
+  }
+
+  /**
+   * 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)'
+   */
+  public unwatch(...signals: (State | Computed)[]) {
+    if (GLOBAL_STATE.frozen) {
+      throw new Error('Cannot unwatch signals while frozen');
+    }
+
+    signals.forEach(signal => {
+      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.#state === 'watching') {
+      this.#state = 'waiting';
+    }
+  }
+
+  /**
+   * Get the current state of the Watcher.
+   * @param symbol - The private symbol for prevent external calls.
+   */
+  public getState(symbol: symbol): WatcherState {
+    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.
+   */
+  public setState(newState: WatcherState, symbol: symbol): void {
+    assertPrivateContext(symbol);
+
+    if (this.#state !== newState && this.#isValidTransition(this.#state, newState)) {
+      this.#state = newState;
+    }
+  }
+
+  /**
+   * Invoce the notify callback when a watched dependency changes
+   * @param symbol - The private symbol for prevent external calls.
+   */
+  public notify(symbol: symbol): void {
+    assertPrivateContext(symbol);
+
+    this.#state = 'pending';
+
+    GLOBAL_STATE.frozen = true;
+    try {
+      this.#notifyCallback.call(this);
+    } finally {
+      this.#state = 'waiting'; 
+      GLOBAL_STATE.frozen = false;
+    }
+  }
+
+  #isValidTransition(from: WatcherState, to: WatcherState): boolean {
+    switch (from) {
+      case 'waiting':
+        return to === 'watching';
+      case 'watching':
+        return to === 'pending' || to === 'waiting';
+      case 'pending':
+        return to === 'waiting';
+    }
+  }
+}

package/src/lib/private-symbol.ts

@@ -0,0 +1,24 @@
+/**
+ * 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
+ */
+export const 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
+ */
+export function assertPrivateContext(symbol: symbol): void {
+  if (symbol !== PRIVATE) {
+    throw new Error('Invalid symbol');
+  }
+}

package/src/lib/subtle.ts

@@ -0,0 +1,79 @@
+import { GLOBAL_STATE } from './globals';
+import { Computed } from './models/computed';
+import { State } from './models/state';
+import { Watcher } from './models/watcher';
+import { PRIVATE } from './private-symbol';
+
+/**
+ * Executes a function without tracking any dependencies.
+ * @param fn - The function to execute without tracking.
+ * @returns The result of the function execution.
+ */
+export function untrack<T>(fn: () => T): T {
+  const prevComputing = GLOBAL_STATE.computing;
+  GLOBAL_STATE.computing = null;
+
+  try {
+    return fn();
+  } 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.
+ */
+export function currentComputed(): Computed | null {
+  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 s - The `Computed` or `Watcher` to introspect.
+ * @returns An array of `State` and `Computed` instances.
+ */
+export function introspectSources(s: Computed | Watcher): (State | Computed)[] {
+  return s.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.
+ */
+export function introspectSinks(signal: State | Computed): (Computed | Watcher)[] {
+  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.
+ */
+export function hasSinks(signal: State | Computed): boolean {
+  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.
+ */
+export function hasSources(signal: Computed | Watcher): boolean {
+  return signal.getSources(PRIVATE).length > 0;
+}

package/src/lib/types/computed-state.type.ts

@@ -0,0 +1,9 @@
+/**
+ * Rapresents the state of a computed signal. 
+ * The state can be one of the following:
+ * - `dirty`: the computed signal is dirty and needs to be recomputed.
+ * - `checked`: the computed signal is checked and needs to be recomputed.
+ * - `computing`: the computed signal is currently being computed.
+ * - `clean`: the computed signal is clean and does not need to be recomputed.
+ */
+export type ComputedState = 'dirty' | 'checked' | 'computing' | 'clean';

package/src/lib/types/global-state.type.ts

@@ -0,0 +1,42 @@
+import { Computed } from '../models/computed';
+
+export type GlobalState = {
+  /**
+   * The innermost `Signal.Computed` (or effect Signal) currently being
+   * re-evaluated as a side-effect of a `.get()` call.
+   *
+   * All Signal reads that occur while this is non-null will register
+   * themselves as sources of this computed, enabling automatic dependency
+   * tracking.
+   *
+   * Set to `null` when no computed is being evaluated (i.e. a 'root' read).
+   *
+   * @see Signal algorithms — 'Hidden global state'
+   */
+  computing: Computed | null;
+  /**
+ * Whether a callback is currently executing that requires the Signal graph
+ * to remain unmodified for the duration of its execution.
+ *
+ * When `true`, any attempt to read or write a Signal will throw an exception.
+ * This prevents the graph from being mutated while it is being traversed,
+ * which would risk exposing inconsistent or half-processed state.
+ *
+ * Set to `true` immediately before invoking:
+ * - The `notify` callback of a `Signal.subtle.Watcher` (during `State.prototype.set`)
+ * - The `watched` callback (during `Watcher.prototype.watch`)
+ * - The `unwatched` callback (during `Watcher.prototype.unwatch`)
+ *
+ * Restored to `false` in a `finally` block after each such callback returns
+ * (or throws), guaranteeing the flag is never left permanently set.
+ *
+ * Note: `Signal.subtle.untrack` does NOT clear this flag — frozen is always
+ * respected regardless of tracking context.
+ *
+ * @see Signal algorithms — 'Hidden global state'
+ * @see Method: `Signal.State.prototype.set`
+ * @see Method: `Signal.subtle.Watcher.prototype.watch`
+ * @see Method: `Signal.subtle.Watcher.prototype.unwatch`
+ */
+  frozen: boolean;
+};

package/src/lib/types/signal-equal.type.ts

@@ -0,0 +1,8 @@
+import { Computed } from "../models/computed";
+import { State } from "../models/state";
+
+/**
+ * A function that compares two values of type `T` and returns `true` if they are considered equal, or `false` otherwise. 
+ * This function is used to determine if a signal's value has changed and if dependent computations need to be re-evaluated.
+ */
+export type SignalEqual<T> = (this: State<T> | Computed<T>, t: T, t2: T) => boolean;

package/src/lib/types/signal-options.type.ts

@@ -0,0 +1,19 @@
+import { Computed } from '../models/computed';
+import { State } from '../models/state';
+import { SignalEqual } from './signal-equal.type';
+
+export type SignalOptions<T> = {
+  /**
+   * Custom comparison function between old and new value. Default: Object.is.
+   * The signal is passed in as the this value for context.
+   */
+  equals?: SignalEqual<T>;
+  /**
+   * Callback called when isWatched becomes true, if it was previously false
+   */
+  watched?: (this: State<T> | Computed<T>) => void;
+  /**
+   * Callback called whenever isWatched becomes false, if it was previously true
+   */
+  unwatched?: (this: State<T> | Computed<T>) => void;
+}

package/src/lib/types/watcher-state.type.ts

@@ -0,0 +1,7 @@
+/**
+ * Type of the state of a watcher.
+ * - `waiting`: The watcher is waiting for its dependencies to change.
+ * - `watching`: The watcher is currently watching its dependencies for changes.
+ * - `pending`: The watcher has been notified of a change and is pending re-evaluation.
+ */
+export type WatcherState = 'waiting' | 'watching' | 'pending';

package/src/public-api.ts

@@ -0,0 +1 @@
+export * from './lib/load-signals';

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json",
+}

package/vite.config.ts

@@ -0,0 +1,16 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { defineConfig } from 'vite';
+import getViteConfig from '../../vite-config';
+
+export default defineConfig(getViteConfig('@xaendar/signals', __dirname, {
+  plugins: [
+    {
+      name: 'types',
+      writeBundle() {
+        const content = readFileSync('../packages/signals/src/globals.d.ts', 'utf-8');
+        const dtsContent = readFileSync('../dist/@xaendar/signals/xaendar-signals.es.d.ts', 'utf-8');
+        writeFileSync('../dist/@xaendar/signals/xaendar-signals.es.d.ts', `${content}\n\n${dtsContent}`);
+      }
+    }
+  ]
+}));