@mmstack/primitives 19.2.3 → 20.0.0

package/index.d.ts

@@ -1,11 +1,1306 @@
-export * from './lib/debounced';
-export * from './lib/derived';
-export * from './lib/element-visibility';
-export * from './lib/map-array';
-export * from './lib/mutable';
-export * from './lib/sensors';
-export * from './lib/stored';
-export * from './lib/throttled';
-export * from './lib/to-writable';
-export * from './lib/until';
-export * from './lib/with-history';
+import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, ElementRef, Injector, ValueEqualityFn } from '@angular/core';
+import { UnknownObject } from '@mmstack/object';
+
+/**
+ * Options for creating a debounced writable signal.
+ * Extends Angular's `CreateSignalOptions` with a debounce time setting.
+ *
+ * @template T The type of value held by the signal.
+ */
+type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {
+    /**
+     * The debounce delay in milliseconds. Specifies how long to wait after the
+     * last `set` or `update` call before the debounced signal reflects the new value.
+     */
+    ms?: number;
+    /**
+     * Optional `DestroyRef` to clean up the debounce timer when the signal is destroyed.
+     * If provided, the timer will be cleared when the signal is destroyed.
+     * If the signal is called within a reactive context a DestroyRef is injected automatically.
+     * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)
+     */
+    destroyRef?: DestroyRef;
+};
+/**
+ * A specialized `WritableSignal` whose publicly readable value updates are debounced.
+ *
+ * It provides access to the underlying, non-debounced signal via the `original` property.
+ *
+ * @template T The type of value held by the signal.
+ */
+type DebouncedSignal<T> = WritableSignal<T> & {
+    /**
+     * A reference to the original, inner `WritableSignal`.
+     * This signal's value is updated *immediately* upon calls to `set` or `update`
+     * on the parent `DebouncedSignal`. Useful for accessing the latest value
+     * without the debounce delay.
+     */
+    original: Signal<T>;
+};
+/**
+ * A convenience function that creates and debounces a new `WritableSignal` in one step.
+ *
+ * @see {debounce} for the core implementation details.
+ *
+ * @template T The type of value the signal holds.
+ * @param initial The initial value of the signal.
+ * @param opt Options for signal creation, including debounce time `ms`.
+ * @returns A `DebouncedSignal<T>` instance.
+ *
+ * @example
+ * // The existing example remains perfect here.
+ * const query = debounced('', { ms: 500 });
+ * effect(() => console.log('Debounced Query:', query()));
+ * query.set('abc');
+ * // ...500ms later...
+ * // Output: Debounced Query: abc
+ */
+declare function debounced<T>(initial: T, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;
+/**
+ * Wraps an existing `WritableSignal` to create a new one whose readable value is debounced.
+ *
+ * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`
+ * read of the source signal to control when the debounced value is re-evaluated.
+ *
+ * @template T The type of value the signal holds.
+ * @param source The source `WritableSignal` to wrap. Writes are applied to this signal immediately.
+ * @param opt Options for debouncing, including debounce time `ms` and an optional `DestroyRef`.
+ * @returns A new `DebouncedSignal<T>` whose read value is debounced. The `.original` property
+ * of the returned signal is a reference back to the provided `source` signal.
+ *
+ * @example
+ * ```ts
+ * import { signal, effect } from '@angular/core';
+ *
+ * // 1. Create a standard source signal.
+ * const sourceQuery = signal('');
+ *
+ * // 2. Create a debounced version of it.
+ * const debouncedQuery = debounce(sourceQuery, { ms: 500 });
+ *
+ * // This effect tracks the original signal and runs immediately.
+ * effect(() => {
+ * console.log('Original Query:', debouncedQuery.original());
+ * });
+ *
+ * // This effect tracks the debounced signal and runs after the delay.
+ * effect(() => {
+ * console.log('Debounced Query:', debouncedQuery());
+ * });
+ *
+ * console.log('Setting query to "a"');
+ * debouncedQuery.set('a');
+ * // Output: Original Query: a
+ *
+ * // ...500ms later...
+ * // Output: Debounced Query: a
+ * ```
+ */
+declare function debounce<T>(source: WritableSignal<T>, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;
+
+/**
+ * Options for creating a derived signal using the full `derived` function signature.
+ * @typeParam T - The type of the source signal's value (parent).
+ * @typeParam U - The type of the derived signal's value (child).
+ */
+type CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {
+    /**
+     * A function that extracts the derived value (`U`) from the source signal's value (`T`).
+     */
+    from: (v: T) => U;
+    /**
+     * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.
+     * This establishes the two-way binding.
+     */
+    onChange: (newValue: U) => void;
+};
+/**
+ * A `WritableSignal` that derives its value from another `WritableSignal` (the "source" signal).
+ * It provides two-way binding: changes to the source signal update the derived signal, and
+ * changes to the derived signal update the source signal.
+ *
+ * @typeParam T - The type of the source signal's value (parent).
+ * @typeParam U - The type of the derived signal's value (child).
+ */
+type DerivedSignal<T, U> = WritableSignal<U> & {
+    /**
+     * The function used to derive the derived signal's value from the source signal's value.
+     * This is primarily for internal use and introspection.
+     */
+    from: (v: T) => U;
+};
+/**
+ * Creates a `DerivedSignal` that derives its value from another `WritableSignal`.
+ * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.
+ *
+ * @typeParam T The type of the source signal's value.
+ * @typeParam U The type of the derived signal's value.
+ * @param source The source `WritableSignal`.
+ * @param options An object containing the `from` and `onChange` functions, and optional signal options.
+ * @returns A `DerivedSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const user = signal({ name: 'John', age: 30 });
+ * const name = derived(user, {
+ * from: (u) => u.name,
+ * onChange: (newName) => user.update((u) => ({ ...u, name: newName })),
+ * });
+ *
+ * name.set('Jane'); // Updates the original signal
+ * console.log(user().name); // Outputs: Jane
+ * ```
+ */
+declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOptions<T, U>): DerivedSignal<T, U>;
+/**
+ * Creates a `DerivedSignal` that derives a property from an object held by the source signal.
+ * This overload is a convenient shorthand for accessing object properties.
+ *
+ * @typeParam T The type of the source signal's value (must be an object).
+ * @typeParam TKey The key of the property to derive.
+ * @param source The source `WritableSignal` (holding an object).
+ * @param key The key of the property to derive.
+ * @param options Optional signal options for the derived signal.
+ * @returns A `DerivedSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const user = signal({ name: 'John', age: 30 });
+ * const name = derived(user, 'name');
+ *
+ * console.log(name()); // Outputs: John
+ *
+ * // Update the derived signal, which also updates the source
+ * name.set('Jane');
+ *
+ * console.log(user().name); // Outputs: Jane
+ * ```
+ */
+declare function derived<T extends UnknownObject, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
+/**
+ * Creates a `DerivedSignal` from an array, deriving an element by its index.
+ * This overload is a convenient shorthand for accessing array elements.
+ *
+ * @typeParam T The type of the source signal's value (must be an array).
+ * @param source The source `WritableSignal` (holding an array).
+ * @param index The index of the element to derive.
+ * @param options Optional signal options for the derived signal.
+ * @returns A `DerivedSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const numbers = signal([1, 2, 3]);
+ * const secondNumber = derived(numbers, 1);
+ *
+ * console.log(secondNumber()); // Outputs: 2
+ *
+ * // Update the derived signal, which also updates the source
+ * secondNumber.set(5);
+ *
+ * console.log(numbers()); // Outputs: [1, 5, 3]
+ * ```
+ */
+declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
+/**
+ * Creates a "fake" `DerivedSignal` from a simple value. This is useful for creating
+ * `FormControlSignal` instances that are not directly derived from another signal.
+ * The returned signal's `from` function will always return the initial value.
+ *
+ * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.
+ * @typeParam U - The type of the signal's value.
+ * @param initial - The initial value of the signal.
+ * @returns A `DerivedSignal` instance.
+ * @internal
+ */
+declare function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U>;
+/**
+ * Creates a "fake" `DerivedSignal` from an existing `WritableSignal`. This is useful
+ * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.
+ *  The returned signal's `from` function returns the current value of signal, using `untracked`.
+ *
+ * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.
+ * @typeParam U - The type of the signal's value.
+ * @param initial - The existing `WritableSignal`.
+ * @returns A `DerivedSignal` instance.
+ * @internal
+ */
+declare function toFakeSignalDerivation<T, U>(initial: WritableSignal<U>): DerivedSignal<T, U>;
+/**
+ * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.
+ *
+ * @typeParam T - The type of the source signal's value (optional, defaults to `any`).
+ * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).
+ * @param sig - The `WritableSignal` to check.
+ * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.
+ */
+declare function isDerivation<T, U>(sig: WritableSignal<U>): sig is DerivedSignal<T, U>;
+
+/**
+ * Options for configuring the `elementVisibility` sensor, extending
+ * standard `IntersectionObserverInit` options.
+ */
+type ElementVisibilityOptions = IntersectionObserverInit & {
+    /** Optional debug name for the internal signal. */
+    debugName?: string;
+};
+type ElementVisibilitySignal = Signal<IntersectionObserverEntry | undefined> & {
+    readonly visible: Signal<boolean>;
+};
+/**
+ * Creates a read-only signal that tracks the intersection status of a target DOM element
+ * with the viewport or a specified root element, using the `IntersectionObserver` API.
+ *
+ * It can observe a static `ElementRef`/`Element` or a `Signal` that resolves to one,
+ * allowing for dynamic targets.
+ *
+ * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
+ * If the signal resolves to `null`, observation stops.
+ * @param options Optional `IntersectionObserverInit` options (e.g., `root`, `rootMargin`, `threshold`)
+ * and an optional `debugName`.
+ * @returns A `Signal<IntersectionObserverEntry | undefined>`. It emits `undefined` initially,
+ * on the server, or if the target is `null`. Otherwise, it emits the latest
+ * `IntersectionObserverEntry`. Consumers can derive a boolean `isVisible` from
+ * this entry's `isIntersecting` property.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, ElementRef, viewChild } from '@angular/core';
+ * import { elementVisibility } from '@mmstack/primitives';
+ * import { computed } from '@angular/core'; // For derived boolean
+ *
+ * @Component({
+ * selector: 'app-lazy-image',
+ * template: `
+ * <div #imageContainer style="height: 200px; border: 1px dashed grey;">
+ * @if (isVisible()) {
+ * <img src="your-image-url.jpg" alt="Lazy loaded image" />
+ * <p>Image is VISIBLE!</p>
+ * } @else {
+ * <p>Scroll down to see the image...</p>
+ * }
+ * </div>
+ * `
+ * })
+ * export class LazyImageComponent {
+ * readonly imageContainer = viewChild.required<ElementRef<HTMLDivElement>>('imageContainer');
+ *
+ * // Observe the element, get the full IntersectionObserverEntry
+ * readonly intersectionEntry = elementVisibility(this.imageContainer);
+ *
+ * // Derive a simple boolean for visibility
+ * readonly isVisible = computed(() => this.intersectionEntry()?.isIntersecting ?? false);
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Intersection Entry:', this.intersectionEntry());
+ * console.log('Is Visible:', this.isVisible());
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;
+
+/**
+ * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
+ *
+ * This function serves a similar purpose to SolidJS's `mapArray` by providing stability
+ * for mapped items. It receives a source function returning an array (or a Signal<T[]>)
+ * and a mapping function.
+ *
+ * For each item in the source array, it creates a stable `computed` signal representing
+ * that item's value at its current index. This stable signal (`Signal<T>`) is passed
+ * to the mapping function. This ensures that downstream computations or components
+ * depending on the mapped result only re-render or re-calculate for the specific items
+ * that have changed, or when items are added/removed, rather than re-evaluating everything
+ * when the source array reference changes but items remain the same.
+ *
+ * It efficiently handles changes in the source array's length by reusing existing mapped
+ * results when possible, slicing when the array shrinks, and appending new mapped items
+ * when it grows.
+ *
+ * @template T The type of items in the source array.
+ * @template U The type of items in the resulting mapped array.
+ *
+ * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.
+ * The `mapArray` function will reactively update based on changes to this source.
+ * @param map The mapping function. It is called for each item in the source array.
+ * It receives:
+ * - `value`: A stable `Signal<T>` representing the item at the current index.
+ * Use this signal within your mapping logic if you need reactivity
+ * tied to the specific item's value changes.
+ * - `index`: The number index of the item in the array.
+ * It should return the mapped value `U`.
+ * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly
+ * to the `computed` signal created for each individual item (`Signal<T>`).
+ * This allows specifying options like a custom `equal` function for item comparison.
+ *
+ * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever
+ * the source array changes (either length or the values of its items).
+ *
+ * @example
+ * ```ts
+ * const sourceItems = signal([
+ * { id: 1, name: 'Apple' },
+ * { id: 2, name: 'Banana' }
+ * ]);
+ *
+ * const mappedItems = mapArray(
+ * sourceItems,
+ * (itemSignal, index) => {
+ * // itemSignal is stable for a given item based on its index.
+ * // We create a computed here to react to changes in the item's name.
+ *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);
+ * },
+ * // Example optional options (e.g., custom equality for item signals)
+ * { equal: (a, b) => a.id === b.id && a.name === b.name }
+ * );
+ * ```
+ * @remarks
+ * This function achieves its high performance by leveraging the new `linkedSignal`
+ * API from Angular, which allows for efficient memoization and reuse of array items.
+ */
+declare function mapArray<T, U>(source: () => T[], map: (value: Signal<T>, index: number) => U, opt?: CreateSignalOptions<T>): Signal<U[]>;
+
+/**
+ * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.
+ * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful
+ * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary
+ * object copying.
+ *
+ * @typeParam T - The type of value held by the signal.
+ */
+type MutableSignal<T> = WritableSignal<T> & {
+    /**
+     * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for
+     * scenarios where you want to modify the existing object directly rather than creating a new one.
+     *
+     * @param updater - A function that takes the current value as input and modifies it directly.
+     *
+     * @example
+     * const myArray = mutable([1, 2, 3]);
+     * myArray.mutate((arr) => {
+     *  arr.push(4);
+     *  return arr;
+     * }); // myArray() now returns [1, 2, 3, 4]
+     */
+    mutate: WritableSignal<T>['update'];
+    /**
+     * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater
+     * function. This further emphasizes that the mutation is happening inline, improving readability
+     * in some cases.
+     * @param updater - Function to change to the current value
+     * @example
+     * const myObject = mutable({ a: 1, b: 2 });
+     * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }
+     */
+    inline: (updater: (value: T) => void) => void;
+};
+/**
+ * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide
+ * the additional `mutate` and `inline` methods.
+ *
+ * @typeParam T The type of value held by the signal.
+ * @param initial The initial value of the signal.
+ * @param options Optional signal options, including a custom `equal` function.
+ * @returns A `MutableSignal` instance.
+ *
+ * ### Important Note on `computed` Signals
+ *
+ * When creating a `computed` signal that derives a non-primitive value (e.g., an object or array)
+ * from a `mutable` signal, you **must** provide the `{ equal: false }` option to the `computed`
+ * function.
+ *
+ * This is because a `.mutate()` call notifies its dependents that it has changed, but if the
+ * reference to a derived object hasn't changed, the `computed` signal will not trigger its
+ * own dependents by default.
+ *
+ * @example
+ * ```ts
+ * const state = mutable({ user: { name: 'John' }, lastUpdated: new Date() });
+ *
+ * // ✅ CORRECT: Deriving a primitive value works as expected.
+ * const name = computed(() => state().user.name);
+ *
+ * // ❌ INCORRECT: This will not update reliably after the first change.
+ * const userObject = computed(() => state().user);
+ *
+ * // ✅ CORRECT: For object derivations, `equal: false` is required.
+ * const userObjectFixed = computed(() => state().user, { equal: false });
+ *
+ * // This mutation will now correctly trigger effects depending on `userObjectFixed`.
+ * state.mutate(s => s.lastUpdated = new Date());
+ * ```
+ */
+declare function mutable<T>(): MutableSignal<T | undefined>;
+declare function mutable<T>(initial: T): MutableSignal<T>;
+declare function mutable<T>(initial: T, opt?: CreateSignalOptions<T>): MutableSignal<T>;
+/**
+ * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful
+ * for situations where you need to conditionally use the `mutate` or `inline` methods.
+ *
+ * @typeParam T - The type of the signal's value (optional, defaults to `any`).
+ * @param value - The `WritableSignal` to check.
+ * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.
+ *
+ * @example
+ * const mySignal = signal(0);
+ * const myMutableSignal = mutable(0);
+ *
+ * if (isMutable(mySignal)) {
+ *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.
+ * }
+ *
+ * if (isMutable(myMutableSignal)) {
+ *   myMutableSignal.mutate(x => x + 1); // This is safe.
+ * }
+ */
+declare function isMutable<T = any>(value: WritableSignal<T>): value is MutableSignal<T>;
+
+/**
+ * Creates a read-only signal that reactively tracks whether a CSS media query
+ * string currently matches.
+ *
+ * It uses `window.matchMedia` to evaluate the query and listen for changes.
+ * The primitive is SSR-safe (defaults to `false` on the server) and automatically
+ * cleans up its event listeners when the creating context is destroyed.
+ *
+ * @param query The CSS media query string to evaluate (e.g., `'(min-width: 768px)'`, `'(prefers-color-scheme: dark)'`).
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<boolean>` which is `true` if the media query
+ * currently matches, and `false` otherwise.
+ *
+ * @remarks
+ * - On the server, this signal will always return `false` by default.
+ * - It automatically updates if the match status of the media query changes in the browser.
+ * - Event listeners are cleaned up automatically via `DestroyRef` if created in an injection context.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { mediaQuery } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-responsive-layout',
+ * template: `
+ * @if (isDesktop()) {
+ * <p>Showing desktop layout.</p>
+ * } @else {
+ * <p>Showing mobile layout.</p>
+ * }
+ * `
+ * })
+ * export class ResponsiveLayoutComponent {
+ * readonly isDesktop = mediaQuery('(min-width: 1024px)');
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Is desktop view:', this.isDesktop());
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function mediaQuery(query: string, debugName?: string): Signal<boolean>;
+/**
+ * Creates a read-only signal that tracks the user's OS/browser preference
+ * for a dark color scheme using the `(prefers-color-scheme: dark)` media query.
+ *
+ * This is a convenience wrapper around the generic `mediaQuery` primitive.
+ * It's SSR-safe (defaults to `false` on the server) and automatically
+ * cleans up its event listeners.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<boolean>` which is `true` if a dark theme
+ * is preferred, and `false` otherwise.
+ * @see {mediaQuery} for the underlying implementation.
+ *
+ * @example
+ * ```ts
+ * const isDarkMode = prefersDarkMode();
+ * effect(() => {
+ * document.body.classList.toggle('dark-theme', isDarkMode());
+ * });
+ * ```
+ */
+declare function prefersDarkMode(debugName?: string): Signal<boolean>;
+/**
+ * Creates a read-only signal that tracks the user's OS/browser preference
+ * for reduced motion using the `(prefers-reduced-motion: reduce)` media query.
+ *
+ * This is a convenience wrapper around the generic `mediaQuery` primitive.
+ * It's SSR-safe (defaults to `false` on the server) and automatically
+ * cleans up its event listeners.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<boolean>` which is `true` if reduced motion
+ * is preferred, and `false` otherwise.
+ * @see {mediaQuery} for the underlying implementation.
+ *
+ * @example
+ * ```ts
+ * const reduceMotion = prefersReducedMotion();
+ * effect(() => {
+ * if (reduceMotion()) {
+ * // Apply simplified animations or disable them
+ * } else {
+ * // Apply full animations
+ * }
+ * });
+ * ```
+ */
+declare function prefersReducedMotion(debugName?: string): Signal<boolean>;
+
+type MousePosition = {
+    x: number;
+    y: number;
+};
+/**
+ * Options for configuring the `mousePosition` sensor.
+ */
+type MousePositionOptions = {
+    /**
+     * The target element to listen for mouse movements on.
+     * Can be `window`, `document`, an `HTMLElement`, or an `ElementRef<HTMLElement>`.
+     * @default window
+     */
+    target?: Window | Document | HTMLElement | ElementRef<HTMLElement>;
+    /**
+     * Defines the coordinate system for the reported position.
+     * - `'client'`: Coordinates relative to the viewport (`clientX`, `clientY`).
+     * - `'page'`: Coordinates relative to the entire document (`pageX`, `pageY`).
+     * @default 'client'
+     */
+    coordinateSpace?: 'client' | 'page';
+    /**
+     * If `true`, the sensor will also listen to `touchmove` events and report
+     * the coordinates of the first touch point.
+     * @default false
+     */
+    touch?: boolean;
+    /**
+     * Optional debug name for the internal signal.
+     */
+    debugName?: string;
+    /**
+     * Optional delay in milliseconds to throttle the updates.
+     * @default 100
+     */
+    throttle?: number;
+};
+/**
+ * A specialized Signal that tracks mouse position within an element.
+ * It's a throttled signal of the mouse coordinates with an attached `unthrottled` signal.
+ */
+type MousePositionSignal = Signal<MousePosition> & {
+    /** A signal providing the raw, unthrottled mouse position. */
+    readonly unthrottled: Signal<MousePosition>;
+};
+/**
+ * Creates a read-only signal that tracks the mouse cursor's position.
+ *
+ * It can track mouse movements on a specific target (window, document, or element)
+ * and optionally include touch movements. The coordinate space ('client' or 'page')
+ * can also be configured.
+ * The primitive is SSR-safe and automatically cleans up its event listeners.
+ *
+ * @param options Optional configuration for the sensor.
+ * @returns A read-only `Signal<MousePosition>`. On the server, it returns a static
+ * signal with `{ x: 0, y: 0 }`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { mousePosition } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-mouse-tracker',
+ * template: `<p>Mouse Position: X: {{ pos().x }}, Y: {{ pos().y }}</p>`
+ * })
+ * export class MouseTrackerComponent {
+ * readonly pos = mousePosition({ coordinateSpace: 'page' });
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Mouse moved to:', this.pos());
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function mousePosition(opt?: MousePositionOptions): MousePositionSignal;
+
+/**
+ * A specialized Signal that tracks network status.
+ * It's a boolean signal with an attached `since` signal.
+ */
+type NetworkStatusSignal = Signal<boolean> & {
+    /** A signal tracking the timestamp of the last status change. */
+    readonly since: Signal<Date>;
+};
+/**
+ * Creates a read-only signal that tracks the browser's online status.
+ *
+ * The main signal returns a boolean (`true` for online, `false` for offline).
+ * An additional `since` signal is attached, tracking when the status last changed.
+ * It's SSR-safe and automatically cleans up its event listeners.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A `NetworkStatusSignal` instance.
+ */
+declare function networkStatus(debugName?: string): NetworkStatusSignal;
+
+/**
+ * Creates a read-only signal that tracks the page's visibility state.
+ *
+ * It uses the browser's Page Visibility API to reactively report if the
+ * current document is `'visible'`, `'hidden'`, or in another state.
+ * The primitive is SSR-safe and automatically cleans up its event listeners
+ * when the creating context is destroyed.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<DocumentVisibilityState>`. On the server,
+ * it returns a static signal with a value of `'visible'`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { pageVisibility } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-visibility-tracker',
+ * template: `<p>Page is currently: {{ visibilityState() }}</p>`
+ * })
+ * export class VisibilityTrackerComponent {
+ * readonly visibilityState = pageVisibility();
+ *
+ * constructor() {
+ * effect(() => {
+ * if (this.visibilityState() === 'hidden') {
+ * console.log('Page is hidden, pausing expensive animations...');
+ * } else {
+ * console.log('Page is visible, resuming activity.');
+ * }
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function pageVisibility(debugName?: string): Signal<DocumentVisibilityState>;
+
+/**
+ * Represents the scroll position.
+ */
+type ScrollPosition = {
+    /** The horizontal scroll position (pixels from the left). */
+    readonly x: number;
+    /** The vertical scroll position (pixels from the top). */
+    readonly y: number;
+};
+/**
+ * Options for configuring the `scrollPosition` sensor.
+ */
+type ScrollPositionOptions = {
+    /**
+     * The target to listen for scroll events on.
+     * Can be `window` (for page scroll) or an `HTMLElement`/`ElementRef<HTMLElement>`.
+     * @default window
+     */
+    target?: Window | HTMLElement | ElementRef<HTMLElement>;
+    /**
+     * Optional delay in milliseconds to throttle the updates.
+     * Scroll events can fire very rapidly.
+     * @default 100 // A common default for scroll throttling
+     */
+    throttle?: number;
+    /** Optional debug name for the internal signal. */
+    debugName?: string;
+};
+/**
+ * A specialized Signal that tracks scroll position.
+ * It's a throttled signal of the scroll coordinates with an attached `unthrottled` signal.
+ */
+type ScrollPositionSignal = Signal<ScrollPosition> & {
+    /** A signal providing the raw, unthrottled scroll position. */
+    readonly unthrottled: Signal<ScrollPosition>;
+};
+/**
+ * Creates a read-only signal that tracks the scroll position (x, y) of the window
+ * or a specified HTML element.
+ *
+ * Updates are throttled by default to optimize performance. An `unthrottled`
+ * property is available on the returned signal for direct access to raw updates.
+ * The primitive is SSR-safe and automatically cleans up its event listeners.
+ *
+ * @param options Optional configuration for the scroll sensor.
+ * @returns A `ScrollPositionSignal`. On the server, it returns a static
+ * signal with `{ x: 0, y: 0 }`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, ElementRef, viewChild } from '@angular/core';
+ * import { scrollPosition } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-scroll-tracker',
+ * template: `
+ * <p>Window Scroll: X: {{ windowScroll().x }}, Y: {{ windowScroll().y }}</p>
+ * <div #scrollableDiv style="height: 200px; width: 200px; overflow: auto; border: 1px solid black;">
+ * <div style="height: 400px; width: 400px;">Scroll me!</div>
+ * </div>
+ * @if (divScroll()) {
+ * <p>Div Scroll: X: {{ divScroll().x }}, Y: {{ divScroll().y }}</p>
+ * }
+ * `
+ * })
+ * export class ScrollTrackerComponent {
+ * readonly windowScroll = scrollPosition(); // Defaults to window
+ * readonly scrollableDiv = viewChild<ElementRef<HTMLDivElement>>('scrollableDiv');
+ * readonly divScroll = scrollPosition({ target: this.scrollableDiv() }); // Example with element target
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Window scrolled to:', this.windowScroll());
+ * if (this.divScroll()) {
+ * console.log('Div scrolled to:', this.divScroll());
+ * }
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function scrollPosition(opt?: ScrollPositionOptions): ScrollPositionSignal;
+
+/**
+ * Represents the dimensions of the window.
+ */
+type WindowSize = {
+    /** The current inner width of the window in pixels. */
+    readonly width: number;
+    /** The current inner height of the window in pixels. */
+    readonly height: number;
+};
+/**
+ * Options for configuring the `mousePosition` sensor.
+ */
+type WindowSizeOptions = {
+    /**
+     * Optional debug name for the internal signal.
+     */
+    debugName?: string;
+    /**
+     * Optional delay in milliseconds to throttle the updates.
+     * @default 100
+     */
+    throttle?: number;
+};
+/**
+ * A specialized Signal that tracks window size.
+ * It's a throttled signal of the window.innerHeight/innerWidth properties
+ * with an attached `unthrottled` signal.
+ */
+type WindowSizeSignal = Signal<WindowSize> & {
+    /** A signal providing the raw, unthrottled window size. */
+    readonly unthrottled: Signal<WindowSize>;
+};
+/**
+ * Creates a read-only signal that tracks the browser window's inner dimensions (width and height).
+ *
+ * Updates are throttled by default (100ms) to optimize performance during resize events.
+ * An `unthrottled` property is available on the returned signal for direct access to raw updates.
+ * The primitive is SSR-safe (returns a default size on the server) and automatically
+ * cleans up its event listeners.
+ *
+ * @param opt Optional configuration, including `throttle` (ms) and `debugName`.
+ * @returns A `WindowSizeSignal` (a `Signal<WindowSize>` with an `unthrottled` property).
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { windowSize } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-responsive-header',
+ * template: `
+ * <header>
+ * Current Window Size: {{ size().width }}px x {{ size().height }}px
+ * @if (isMobile()) {
+ * <p>Mobile Menu</p>
+ * } @else {
+ * <p>Desktop Menu</p>
+ * }
+ * </header>
+ * `
+ * })
+ * export class ResponsiveHeaderComponent {
+ * readonly size = windowSize();
+ * readonly isMobile = computed(() => this.size().width < 768);
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Window resized to:', this.size());
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function windowSize(opt?: WindowSizeOptions): WindowSizeSignal;
+
+/**
+ * Creates a sensor signal that tracks the mouse cursor's position.
+ * @param type Must be `'mousePosition'`.
+ * @param options Optional configuration for the mouse position sensor.
+ * @returns A `MousePositionSignal` that tracks mouse coordinates and provides an unthrottled version.
+ * @see {mousePosition} for detailed documentation and examples.
+ * @example const pos = sensor('mousePosition', { coordinateSpace: 'page', throttle: 50 });
+ */
+declare function sensor(type: 'mousePosition', options?: MousePositionOptions): MousePositionSignal;
+/**
+ * Creates a sensor signal that tracks the browser's online/offline status.
+ * @param type Must be `'networkStatus'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `NetworkStatusSignal` which is a boolean indicating online status, with an attached `since` signal.
+ * @see {networkStatus} for detailed documentation and examples.
+ * @example const onlineStatus = sensor('networkStatus');
+ */
+declare function sensor(type: 'networkStatus', options?: {
+    debugName?: string;
+}): NetworkStatusSignal;
+/**
+ * Creates a sensor signal that tracks the page's visibility state (e.g., 'visible', 'hidden').
+ * @param type Must be `'pageVisibility'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `Signal<DocumentVisibilityState>` indicating the page's current visibility.
+ * @see {pageVisibility} for detailed documentation and examples.
+ * @example const visibility = sensor('pageVisibility');
+ */
+declare function sensor(type: 'pageVisibility', options?: {
+    debugName?: string;
+}): Signal<DocumentVisibilityState>;
+/**
+ * Creates a sensor signal that tracks the user's OS/browser preference for a dark color scheme.
+ * @param type Must be `'dark-mode'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `Signal<boolean>` which is `true` if a dark theme is preferred.
+ * @see {prefersDarkMode} for detailed documentation and examples.
+ * @example const isDarkMode = sensor('dark-mode');
+ */
+declare function sensor(type: 'dark-mode', options?: {
+    debugName?: string;
+}): Signal<boolean>;
+/**
+ * Creates a sensor signal that tracks the user's OS/browser preference for reduced motion.
+ * @param type Must be `'reduced-motion'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `Signal<boolean>` which is `true` if reduced motion is preferred.
+ * @see {prefersReducedMotion} for detailed documentation and examples.
+ * @example const wantsReducedMotion = sensor('reduced-motion');
+ */
+declare function sensor(type: 'reduced-motion', options?: {
+    debugName?: string;
+}): Signal<boolean>;
+/**
+ * Creates a sensor signal that tracks the browser window's inner dimensions (width and height).
+ * @param type Must be `'windowSize'`.
+ * @param options Optional configuration for the window size sensor, including `throttle` and `debugName`.
+ * @returns A `WindowSizeSignal` that tracks window dimensions and provides an unthrottled version.
+ * @see {windowSize} for detailed documentation and examples.
+ * @example const size = sensor('windowSize', { throttle: 200 });
+ */
+declare function sensor(type: 'windowSize', options?: WindowSizeOptions): WindowSizeSignal;
+/**
+ * Creates a sensor signal that tracks the scroll position (x, y) of the window or a specified element.
+ * @param type Must be `'scrollPosition'`.
+ * @param options Optional configuration for the scroll position sensor, including `target`, `throttle`, and `debugName`.
+ * @returns A `ScrollPositionSignal` that tracks scroll coordinates and provides an unthrottled version.
+ * @see {scrollPosition} for detailed documentation and examples.
+ * @example const pageScroll = sensor('scrollPosition', { throttle: 150 });
+ */
+declare function sensor(type: 'scrollPosition', options?: ScrollPositionOptions): ScrollPositionSignal;
+
+/**
+ * Interface for storage mechanisms compatible with the `stored` signal.
+ * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
+ */
+type Store = {
+    /** Retrieves an item from storage for a given key. */
+    getItem: (key: string) => string | null;
+    /** Sets an item in storage for a given key. */
+    setItem: (key: string, value: string) => void;
+    /** Removes an item from storage for a given key. */
+    removeItem: (key: string) => void;
+};
+/**
+ * Options for creating a signal synchronized with persistent storage using `stored()`.
+ * Extends Angular's `CreateSignalOptions`.
+ *
+ * @template T The type of value held by the signal.
+ */
+type CreateStoredOptions<T> = CreateSignalOptions<T> & {
+    /**
+     * The key used to identify the item in storage.
+     * Can be a static string or a function/signal returning a string for dynamic keys
+     * (e.g., based on user ID or other application state).
+     */
+    key: string | (() => string);
+    /**
+     * Optional custom storage implementation (e.g., `sessionStorage` or a custom adapter).
+     * Must conform to the `Store` interface (`getItem`, `setItem`, `removeItem`).
+     * Defaults to `localStorage` in browser environments and a no-op store on the server.
+     */
+    store?: Store;
+    /**
+     * Optional function to serialize the value (type `T`) into a string before storing.
+     * Defaults to `JSON.stringify`.
+     * @param {T} value The value to serialize.
+     * @returns {string} The serialized string representation.
+     */
+    serialize?: (value: T) => string;
+    /**
+     * Optional function to deserialize the string retrieved from storage back into the value (type `T`).
+     * Defaults to `JSON.parse`.
+     * @param {string} value The string retrieved from storage.
+     * @returns {T} The deserialized value.
+     */
+    deserialize?: (value: string) => T;
+    /**
+     * If `true`, the signal will attempt to synchronize its state across multiple browser tabs
+     * using the `storage` event. Changes made in one tab (set, update, clear) will be
+     * reflected in other tabs using the same storage key.
+     * Requires a browser environment. Defaults to `false`.
+     */
+    syncTabs?: boolean;
+    /**
+     * Optional parameter to specify how key changes should be handled, load is the default.
+     * - `load`: The signal will load the value from storage when the key changes & replace the signal's value.
+     * - `store`: The signal will store the current value to the new key when the key changes.
+     */
+    onKeyChange?: 'load' | 'store';
+    /**
+     * If 'true', the signal will remove the old key from storage when the key changes, defaults to `false`.
+     */
+    cleanupOldKey?: boolean;
+};
+/**
+ * A specialized `WritableSignal` returned by the `stored()` function.
+ * It synchronizes its value with persistent storage and provides additional methods.
+ *
+ * @template T The type of value held by the signal (matches the fallback type).
+ */
+type StoredSignal<T> = WritableSignal<T> & {
+    /**
+     * Removes the item associated with the signal's key from the configured storage.
+     * After clearing, reading the signal will return the fallback value until it's set again.
+     */
+    clear: () => void;
+    /**
+     * A `Signal<string>` containing the current storage key being used by this stored signal.
+     * This is particularly useful if the key was configured dynamically. You can read or react
+     * to this signal to know the active key.
+     */
+    key: Signal<string>;
+};
+/**
+ * Creates a `WritableSignal` whose state is automatically synchronized with persistent storage
+ * (like `localStorage` or `sessionStorage`).
+ *
+ * It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys,
+ * custom serialization/deserialization, custom storage providers, and optional
+ * synchronization across browser tabs.
+ *
+ * @template T The type of value held by the signal and stored (after serialization).
+ * @param fallback The default value of type `T` to use when no value is found in storage
+ * or when deserialization fails. The signal's value will never be `null` or `undefined`
+ * publicly, it will always revert to this fallback.
+ * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.
+ * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,
+ * but its value is persisted. It includes a `.clear()` method to remove the item from storage
+ * and a `.key` signal providing the current storage key.
+ *
+ * @remarks
+ * - **Persistence:** The signal automatically saves its value to storage whenever the signal's
+ * value or its configured `key` changes. This is managed internally using `effect`.
+ * - **SSR Safety:** Detects server environments and uses a no-op storage, preventing errors.
+ * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.
+ * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value
+ * consistent across browser tabs using the same key. Cleanup is handled automatically
+ * using `DestroyRef`.
+ * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.
+ * Setting the signal to the fallback value will store the fallback value, not remove the item.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, signal } from '@angular/core';
+ * import { stored } from '@mmstack/primitives'; // Adjust import path
+ *
+ * @Component({
+ * selector: 'app-settings',
+ * standalone: true,
+ * template: `
+ * Theme:
+ * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
+ * <option value="light">Light</option>
+ * <option value="dark">Dark</option>
+ * </select>
+ * <button (click)="theme.clear()">Clear Theme Setting</button>
+ * <p>Storage Key Used: {{ theme.key() }}</p>
+ * ` // Requires FormsModule for ngModel
+ * })
+ * export class SettingsComponent {
+ *  theme = stored<'light' | 'dark'>('light', { key: 'app-theme', syncTabs: true });
+ * }
+ * ```
+ */
+declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+
+/**
+ * Options for creating a throttled writable signal.
+ * Extends Angular's `CreateSignalOptions` with a throttle time setting.
+ *
+ * @template T The type of value held by the signal.
+ */
+type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
+    /**
+     * The throttle delay in milliseconds. The minimum time
+     * in milliseconds that must pass between updates to the throttled signal's value.
+     */
+    ms?: number;
+    /**
+     * Optional `DestroyRef` to clean up the throttle timer when the signal is destroyed.
+     * If provided, the timer will be cleared when the signal is destroyed.
+     * If the signal is called within a reactive context a DestroyRef is injected automatically.
+     * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)
+     */
+    destroyRef?: DestroyRef;
+};
+/**
+ * A specialized `WritableSignal` whose publicly readable value updates are throttled.
+ *
+ * It provides access to the underlying, non-throttled signal via the `original` property.
+ *
+ * @template T The type of value held by the signal.
+ * @see {DebouncedSignal} as the output type has the same structure.
+ */
+type ThrottledSignal<T> = DebouncedSignal<T>;
+/**
+ * A convenience function that creates and throttles a new `WritableSignal` in one step.
+ *
+ * @see {throttle} for the core implementation details.
+ *
+ * @template T The type of value the signal holds.
+ * @param initial The initial value of the signal.
+ * @param opt Options for signal creation, including throttle time `ms`.
+ * @returns A `ThrottledSignal<T>` instance.
+ *
+ * @example
+ * const query = throttled('', { ms: 500 });
+ * effect(() => console.log('Throttled Query:', query()));
+ *
+ * query.set('a');
+ * query.set('b');
+ * query.set('c');
+ * // With a trailing-edge throttle, the final value 'c' would be set
+ * // after the 500ms cooldown.
+ */
+declare function throttled<T>(initial: T, opt?: CreateThrottledOptions<T>): DebouncedSignal<T>;
+/**
+ * Wraps an existing `WritableSignal` to create a new one whose readable value is throttled.
+ *
+ * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`
+ * read of the source signal to control when the throttled value is re-evaluated.
+ *
+ * @template T The type of value the signal holds.
+ * @param source The source `WritableSignal` to wrap. Writes are applied to this signal immediately.
+ * @param opt Options for throttling, including throttle time `ms` and an optional `DestroyRef`.
+ * @returns A new `ThrottledSignal<T>` whose read value is throttled. The `.original` property
+ * of the returned signal is a reference back to the provided `source` signal.
+ *
+ * @example
+ * const query = throttled('', { ms: 500 });
+ * effect(() => console.log('Throttled Query:', query()));
+ *
+ * query.set('a');
+ * query.set('b');
+ * query.set('c');
+ * // With a trailing-edge throttle, the final value 'c' would be set
+ * // after the 500ms cooldown.
+ */
+declare function throttle<T>(source: WritableSignal<T>, opt?: CreateThrottledOptions<T>): ThrottledSignal<T>;
+
+/**
+ * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
+ * This can be useful for creating controlled write access to a signal that is otherwise read-only.
+ *
+ * @typeParam T - The type of value held by the signal.
+ *
+ * @param signal - The read-only `Signal` to be made writable.
+ * @param set - A function that will be used to set the signal's value.  This function *must* handle
+ *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).
+ * @param update - (Optional) A function that will be used to update the signal's value based on its
+ *                 previous value.  If not provided, a default `update` implementation is used that
+ *                 calls the provided `set` function with the result of the updater function. The
+ *                 default implementation uses `untracked` to avoid creating unnecessary dependencies
+ *                 within the updater function.
+ *
+ * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`
+ *          method of the returned signal will still return the original read-only signal.
+ *
+ * @example
+ * // Basic usage: Making a read-only signal writable with a custom set function.
+ * const originalValue = signal({a: 0});
+ * const readOnlySignal = computed(() => originalValue().a);
+ * const writableSignal = toWritable(readOnlySignal, (newValue) => {
+ *  originalValue.update((prev) => { ...prev, a: newValue });
+ * });
+ *
+ * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
+ */
+declare function toWritable<T>(signal: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void): WritableSignal<T>;
+
+type UntilOptions = {
+    /**
+     * Optional timeout in milliseconds. If the condition is not met
+     * within this period, the promise will reject.
+     */
+    timeout?: number;
+    /**
+     * Optional DestroyRef. If provided and the component/context is destroyed
+     * before the condition is met or timeout occurs, the promise will reject.
+     * If not provided, it will attempt to inject one if called in an injection context.
+     */
+    destroyRef?: DestroyRef;
+    injector?: Injector;
+};
+/**
+ * Creates a Promise that resolves when a signal's value satisfies a given predicate.
+ *
+ * This is useful for imperatively waiting for a reactive state to change,
+ * for example, in tests or to orchestrate complex asynchronous operations.
+ *
+ * @template T The type of the signal's value.
+ * @param sourceSignal The signal to observe.
+ * @param predicate A function that takes the signal's value and returns `true` if the condition is met.
+ * @param options Optional configuration for timeout and explicit destruction.
+ * @returns A Promise that resolves with the signal's value when the predicate is true,
+ * or rejects on timeout or context destruction.
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ *
+ * async function waitForCount() {
+ * console.log('Waiting for count to be >= 3...');
+ * try {
+ * const finalCount = await until(count, c => c >= 3, { timeout: 5000 });
+ * console.log(`Count reached: ${finalCount}`);
+ * } catch (e: any) { // Ensure 'e' is typed if you access properties like e.message
+ * console.error(e.message); // e.g., "until: Timeout after 5000ms."
+ * }
+ * }
+ *
+ * // Simulate updates
+ * setTimeout(() => count.set(1), 500);
+ * setTimeout(() => count.set(2), 1000);
+ * setTimeout(() => count.set(3), 1500);
+ *
+ * waitForCount();
+ * ```
+ */
+declare function until<T>(sourceSignal: Signal<T>, predicate: (value: T) => boolean, options?: UntilOptions): Promise<T>;
+
+/**
+ * A WritableSignal enhanced with undo/redo capabilities and history tracking.
+ *
+ * @template T The type of value held by the signal.
+ */
+type SignalWithHistory<T> = WritableSignal<T> & {
+    /** A read-only signal of the undo history stack. The oldest changes are at the start of the array. */
+    history: Signal<T[]>;
+    /** Reverts the signal to its most recent previous state in the history. */
+    undo: () => void;
+    /** Re-applies the last state that was undone. */
+    redo: () => void;
+    /** A signal that is `true` if there are states in the redo stack. */
+    canRedo: Signal<boolean>;
+    /** A signal that is `true` if there are states in the undo history. */
+    canUndo: Signal<boolean>;
+    /** Clears both the undo and redo history stacks. */
+    clear: () => void;
+    /** A signal that is `true` if there is any history that can be cleared. */
+    canClear: Signal<boolean>;
+};
+/**
+ * Options for creating a signal with history tracking.
+ *
+ * @template T The type of value held by the signal.
+ */
+type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
+    /**
+     * Optional custom equality function to determine if a value has changed before
+     * adding it to history. Defaults to the source signal's equality function or `Object.is`.
+     */
+    equal?: ValueEqualityFn<T>;
+    /**
+     * The maximum number of undo states to keep in the history.
+     * @default Infinity
+     */
+    maxSize?: number;
+    /**
+     * The strategy for trimming the history when `maxSize` is reached.
+     * - `shift`: Removes the single oldest entry from the history.
+     * - `halve`: Removes the oldest half of the history stack.
+     * @default 'halve'
+     */
+    cleanupStrategy?: 'shift' | 'halve';
+};
+/**
+ * Enhances an existing `WritableSignal` by adding a complete undo/redo history
+ * stack and an API to control it.
+ *
+ * @template T The type of value held by the signal.
+ * @param source The source `WritableSignal` to add history tracking to.
+ * @param options Optional configuration for the history behavior.
+ * @returns A `SignalWithHistory<T>` instance, augmenting the source signal with history APIs.
+ *
+ * @remarks
+ * - Any new `.set()` or `.update()` call on the signal will clear the entire redo stack.
+ * - The primitive attempts to automatically use the source signal's own `equal` function,
+ * but this relies on an internal Angular API. For maximum stability across Angular
+ * versions, it is recommended to provide an explicit `equal` function in the options.
+ *
+ * @example
+ * ```ts
+ * import { signal } from '@angular/core';
+ * import { withHistory } from '@mmstack/primitives';
+ *
+ * const name = withHistory(signal('John'), { maxSize: 5 });
+ *
+ * console.log('Initial value:', name()); // "John"
+ *
+ * name.set('John Doe');
+ * name.set('Jane Doe');
+ *
+ * console.log('Current value:', name()); // "Jane Doe"
+ * console.log('History:', name.history()); // ["John", "John Doe"]
+ * console.log('Can undo:', name.canUndo()); // true
+ * console.log('Can redo:', name.canRedo()); // false
+ *
+ * name.undo();
+ * console.log('After undo:', name()); // "John Doe"
+ * console.log('Can redo:', name.canRedo()); // true
+ *
+ * name.redo();
+ * console.log('After redo:', name()); // "Jane Doe"
+ *
+ * // A new change will clear the redo history
+ * name.set('Janine Doe');
+ * console.log('Can redo:', name.canRedo()); // false
+ *
+ * name.clear();
+ * console.log('Can undo:', name.canUndo()); // false
+ * ```
+ */
+declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
+
+export { debounce, debounced, derived, elementVisibility, isDerivation, isMutable, mapArray, mediaQuery, mousePosition, mutable, networkStatus, pageVisibility, prefersDarkMode, prefersReducedMotion, scrollPosition, sensor, stored, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
+export type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, NetworkStatusSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal };