@mmstack/primitives 19.2.2 → 19.3.0

package/fesm2022/mmstack-primitives.mjs

@@ -1,7 +1,216 @@
-import { untracked, signal, inject, DestroyRef, computed, PLATFORM_ID, isSignal, effect, ElementRef, linkedSignal, isDevMode, Injector, runInInjectionContext } from '@angular/core';
+import * as i0 from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, computed, signal, isSignal, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
+const frameStack = [];
+function currentFrame() {
+    return frameStack.at(-1) ?? null;
+}
+function clearFrame(frame, userCleanups) {
+    frame.parent = null;
+    for (const fn of userCleanups) {
+        try {
+            fn();
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error('Error destroying nested effect:', e);
+        }
+    }
+    userCleanups.length = 0;
+    for (const child of frame.children) {
+        try {
+            child.destroy();
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error('Error destroying nested effect:', e);
+        }
+    }
+    frame.children.clear();
+}
+function pushFrame(frame) {
+    return frameStack.push(frame);
+}
+function popFrame() {
+    return frameStack.pop();
+}
+
+/**
+ * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
+ *
+ * This primitive enables true hierarchical reactivity. A `nestedEffect` created
+ * within another `nestedEffect` is automatically destroyed and recreated when
+ * the parent re-runs.
+ *
+ * It automatically handles injector propagation and lifetime management, allowing
+ * you to create fine-grained, conditional side-effects that only track
+ * dependencies when they are "live".
+ *
+ * @param effectFn The side-effect function, which receives a cleanup register function.
+ * @param options (Optional) Angular's `CreateEffectOptions`.
+ * @returns An `EffectRef` for the created effect.
+ *
+ * @example
+ * ```ts
+ * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
+ * const coldGuard = signal(false);
+ * const hotSignal = signal(0);
+ *
+ * nestedEffect(() => {
+ * // This outer effect only tracks `coldGuard`.
+ * if (coldGuard()) {
+ *
+ * // This inner effect is CREATED when coldGuard is true
+ * // and DESTROYED when it becomes false.
+ * nestedEffect(() => {
+ * // It only tracks `hotSignal` while it exists.
+ * console.log('Hot signal is:', hotSignal());
+ * });
+ * }
+ * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' }
+ * ]);
+ *
+ * // The fine-grained mapped list
+ * const mappedUsers = mapArray(
+ *   users,
+ *   (userSignal, index) => {
+ *     // 1. Create a fine-grained SIDE EFFECT for *this item*
+ *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
+ *     const effectRef = nestedEffect(() => {
+ *       // This only runs if *this* userSignal changes,
+ *       // not if the whole list changes.
+ *       console.log(`User ${index} updated:`, userSignal().name);
+ *     });
+ *
+ *     // 2. Return the data AND the cleanup logic
+ *     return {
+ *       // The mapped data
+ *       label: computed(() => `User: ${userSignal().name}`),
+ *
+ *       // The cleanup function
+ *       destroyEffect: () => effectRef.destroy()
+ *     };
+ *   },
+ *   {
+ *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     onDestroy: (mappedItem) => {
+ *       mappedItem.destroyEffect();
+ *     }
+ *   }
+ * );
+ * ```
+ */
+function nestedEffect(effectFn, options) {
+    const bindToFrame = options?.bindToFrame ?? ((parent) => parent);
+    const parent = bindToFrame(currentFrame());
+    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
+    let isDestroyed = false;
+    const srcRef = untracked(() => {
+        return effect((cleanup) => {
+            if (isDestroyed)
+                return;
+            const frame = {
+                injector,
+                parent,
+                children: new Set(),
+            };
+            const userCleanups = [];
+            pushFrame(frame);
+            try {
+                effectFn((fn) => userCleanups.push(fn));
+            }
+            finally {
+                popFrame();
+            }
+            return cleanup(() => clearFrame(frame, userCleanups));
+        }, {
+            ...options,
+            injector,
+            manualCleanup: options?.manualCleanup ?? !!parent,
+        });
+    });
+    const ref = {
+        destroy: () => {
+            if (isDestroyed)
+                return;
+            isDestroyed = true;
+            parent?.children.delete(ref);
+            srcRef.destroy();
+        },
+    };
+    parent?.children.add(ref);
+    injector.get(DestroyRef).onDestroy(() => ref.destroy());
+    return ref;
+}
+
+/**
+ * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
+ *
+ * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `duration`.
+ *
+ * @template T The type of items in the array.
+ * @param source A `Signal` or a function that returns an array of items to be processed in chunks.
+ * @param options Configuration options for chunk size, delay duration, equality function, and injector.
+ * @returns A `Signal` that emits the current chunk of items being processed.
+ *
+ * @example
+ * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
+ * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ */
+function chunked(source, options) {
+    const { chunkSize = 50, delay = 'frame', equal, injector } = options || {};
+    let delayFn;
+    if (delay === 'frame') {
+        delayFn = (callback) => {
+            const num = requestAnimationFrame(callback);
+            return () => cancelAnimationFrame(num);
+        };
+    }
+    else if (delay === 'microtask') {
+        delayFn = (cb) => {
+            let isCancelled = false;
+            queueMicrotask(() => {
+                if (isCancelled)
+                    return;
+                cb();
+            });
+            return () => {
+                isCancelled = true;
+            };
+        };
+    }
+    else {
+        delayFn = (cb) => {
+            const num = setTimeout(cb, delay);
+            return () => clearTimeout(num);
+        };
+    }
+    const internal = linkedSignal({
+        source,
+        computation: (items) => items.slice(0, chunkSize),
+        equal,
+    });
+    nestedEffect((cleanup) => {
+        const fullList = source();
+        const current = internal();
+        if (current.length >= fullList.length)
+            return;
+        return cleanup(delayFn(() => untracked(() => internal.set(fullList.slice(0, current.length + chunkSize)))));
+    }, {
+        injector: injector,
+    });
+    return internal.asReadonly();
+}
+
 /**
  * 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.
@@ -30,9 +239,9 @@ import { SIGNAL } from '@angular/core/primitives/signals';
  *
  * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
  */
-function toWritable(signal, set, update) {
-    const internal = signal;
-    internal.asReadonly = () => signal;
+function toWritable(source, set, update, opt) {
+    const internal = (opt?.pure !== false ? computed(source) : source);
+    internal.asReadonly = () => source;
     internal.set = set;
     internal.update = update ?? ((updater) => set(updater(untracked(internal))));
     return internal;
@@ -114,19 +323,19 @@ function debounce(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (afterClean) => {
+    const triggerFn = (next) => {
         if (timeout)
             clearTimeout(timeout);
-        afterClean();
+        source.set(next);
         timeout = setTimeout(() => {
             trigger.update((c) => !c);
         }, ms);
     };
     const set = (value) => {
-        triggerFn(() => source.set(value));
+        triggerFn(value);
     };
     const update = (fn) => {
-        triggerFn(() => source.update(fn));
+        triggerFn(fn(untracked(source)));
     };
     const writable = toWritable(computed(() => {
         trigger();
@@ -136,25 +345,112 @@ function debounce(source, opt) {
     return writable;
 }
 
+const { is } = Object;
+function mutable(initial, opt) {
+    const baseEqual = opt?.equal ?? is;
+    let trigger = false;
+    const equal = (a, b) => {
+        if (trigger)
+            return false;
+        return baseEqual(a, b);
+    };
+    const sig = signal(initial, {
+        ...opt,
+        equal,
+    });
+    const internalUpdate = sig.update;
+    sig.mutate = (updater) => {
+        trigger = true;
+        internalUpdate(updater);
+        trigger = false;
+    };
+    sig.inline = (updater) => {
+        sig.mutate((prev) => {
+            updater(prev);
+            return prev;
+        });
+    };
+    return sig;
+}
+/**
+ * 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.
+ * }
+ */
+function isMutable(value) {
+    return 'mutate' in value && typeof value.mutate === 'function';
+}
+
 function derived(source, optOrKey, opt) {
     const isArray = Array.isArray(untracked(source)) && typeof optOrKey === 'number';
     const from = typeof optOrKey === 'object' ? optOrKey.from : (v) => v[optOrKey];
     const onChange = typeof optOrKey === 'object'
         ? optOrKey.onChange
         : isArray
-            ? (next) => {
-                source.update((cur) => {
-                    const newArray = [...cur];
-                    newArray[optOrKey] = next;
-                    return newArray;
-                });
-            }
-            : (next) => {
-                source.update((cur) => ({ ...cur, [optOrKey]: next }));
-            };
-    const rest = typeof optOrKey === 'object' ? optOrKey : opt;
-    const sig = toWritable(computed(() => from(source()), rest), (newVal) => onChange(newVal));
+            ? isMutable(source)
+                ? (next) => {
+                    source.mutate((cur) => {
+                        cur[optOrKey] = next;
+                        return cur;
+                    });
+                }
+                : (next) => {
+                    source.update((cur) => {
+                        const newArray = [...cur];
+                        newArray[optOrKey] = next;
+                        return newArray;
+                    });
+                }
+            : isMutable(source)
+                ? (next) => {
+                    source.mutate((cur) => {
+                        cur[optOrKey] = next;
+                        return cur;
+                    });
+                }
+                : (next) => {
+                    source.update((cur) => ({ ...cur, [optOrKey]: next }));
+                };
+    const rest = typeof optOrKey === 'object' ? { ...optOrKey, ...opt } : opt;
+    const baseEqual = rest?.equal ?? Object.is;
+    let trigger = false;
+    const equal = isMutable(source)
+        ? (a, b) => {
+            if (trigger)
+                return false;
+            return baseEqual(a, b);
+        }
+        : baseEqual;
+    const sig = toWritable(computed(() => from(source()), { ...rest, equal }), (newVal) => onChange(newVal), undefined, { pure: false });
     sig.from = from;
+    if (isMutable(source)) {
+        sig.mutate = (updater) => {
+            trigger = true;
+            sig.update(updater);
+            trigger = false;
+        };
+        sig.inline = (updater) => {
+            sig.mutate((prev) => {
+                updater(prev);
+                return prev;
+            });
+        };
+    }
     return sig;
 }
 /**
@@ -201,6 +497,445 @@ function isDerivation(sig) {
     return 'from' in sig;
 }
 
+function isWritableSignal(value) {
+    return 'set' in value && typeof value.set === 'function';
+}
+/**
+ * @internal
+ * Creates a setter function for a source signal of type `Signal<T[]>` or a function returning `T[]`.
+ * @param source The source signal of type `Signal<T[]>` or a function returning `T[]`.
+ * @returns
+ */
+function createSetter(source) {
+    if (!isWritableSignal(source))
+        return () => {
+            // noop;
+        };
+    if (isMutable(source))
+        return (value, index) => {
+            source.mutate((arr) => {
+                arr[index] = value;
+                return arr;
+            });
+        };
+    return (value, index) => {
+        source.update((arr) => arr.map((v, i) => (i === index ? value : v)));
+    };
+}
+
+/**
+ * Helper to create the derived signal for a specific index.
+ * Extracts the cast logic to keep the main loop clean.
+ */
+function createItemSignal(source, index, setter, opt) {
+    return derived(
+    // We cast to any/Mutable to satisfy the overload signature,
+    // but 'derived' internally checks isMutable() for safety.
+    source, {
+        from: (src) => src[index],
+        onChange: (value) => setter(value, index),
+    }, opt);
+}
+function indexArray(source, map, opt = {}) {
+    const data = isSignal(source) ? source : computed(source);
+    const len = computed(() => data().length);
+    const setter = createSetter(data);
+    const writableData = isWritableSignal(data)
+        ? data
+        : toWritable(data, () => {
+            // noop
+        });
+    if (isWritableSignal(data) && isMutable(data) && !opt.equal) {
+        opt.equal = (a, b) => {
+            if (a !== b)
+                return false; // actually check primitives and references
+            return false; // opt out for same refs
+        };
+    }
+    return linkedSignal({
+        source: () => len(),
+        computation: (len, prev) => {
+            if (!prev)
+                return Array.from({ length: len }, (_, i) => map(createItemSignal(writableData, i, setter, opt), i));
+            if (len === prev.value.length)
+                return prev.value;
+            if (len < prev.value.length) {
+                if (opt.onDestroy) {
+                    for (let i = len; i < prev.value.length; i++) {
+                        opt.onDestroy(prev.value[i]);
+                    }
+                }
+                return prev.value.slice(0, len);
+            }
+            const next = prev.value.slice();
+            for (let i = prev.value.length; i < len; i++)
+                next[i] = map(createItemSignal(writableData, i, setter, opt), i);
+            return next;
+        },
+        equal: (a, b) => a.length === b.length,
+    });
+}
+/**
+ * @deprecated use indexArray instead
+ */
+const mapArray = indexArray;
+
+/**
+ * Reactively maps items from a source array to a new array by value (identity).
+ *
+ * similar to `Array.prototype.map`, but:
+ * 1. The `mapFn` receives the `index` as a Signal.
+ * 2. If an item in the `source` array moves to a new position, the *result* of the map function is reused and moved.
+ *    The `index` signal is updated to the new index.
+ * 3. The `mapFn` is only run for *new* items.
+ *
+ * This is useful for building efficient lists where DOM nodes or heavy instances should be reused
+ * when the list is reordered.
+ *
+ * @param source A `Signal<T[]>` or a function returning `T[]`.
+ * @param mapFn The mapping function. Receives the item and its index as a Signal.
+ * @param options Optional configuration:
+ *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
+ * @returns A `Signal<U[]>` containing the mapped array.
+ */
+function keyArray(source, mapFn, options = {}) {
+    const sourceSignal = isSignal(source) ? source : computed(source);
+    const items = [];
+    let mapped = [];
+    const indexes = [];
+    const getKey = options.key || ((v) => v);
+    const newIndices = new Map();
+    const temp = [];
+    const tempIndexes = [];
+    const newIndicesNext = [];
+    const newIndexesCache = new Array();
+    return computed(() => {
+        const newItems = sourceSignal() || [];
+        return untracked(() => {
+            let i;
+            let j;
+            const newLen = newItems.length;
+            const len = items.length;
+            const newMapped = new Array(newLen);
+            const newIndexes = newIndexesCache;
+            newIndexes.length = 0;
+            newIndexes.length = newLen;
+            let start;
+            let end;
+            let newEnd;
+            let item;
+            let key;
+            if (newLen === 0) {
+                if (len !== 0) {
+                    if (options.onDestroy) {
+                        for (let k = 0; k < len; k++)
+                            options.onDestroy(mapped[k]);
+                    }
+                    items.length = 0;
+                    mapped = [];
+                    indexes.length = 0;
+                }
+                return mapped;
+            }
+            if (len === 0) {
+                for (j = 0; j < newLen; j++) {
+                    item = newItems[j];
+                    items[j] = item;
+                    const indexSignal = signal(j);
+                    newIndexes[j] = indexSignal;
+                    newMapped[j] = mapFn(item, indexSignal);
+                }
+            }
+            else {
+                newIndices.clear();
+                temp.length = 0;
+                tempIndexes.length = 0;
+                newIndicesNext.length = 0;
+                for (start = 0, end = Math.min(len, newLen); start < end && getKey(items[start]) === getKey(newItems[start]); start++) {
+                    newMapped[start] = mapped[start];
+                    newIndexes[start] = indexes[start];
+                }
+                for (end = len - 1, newEnd = newLen - 1; end >= start &&
+                    newEnd >= start &&
+                    getKey(items[end]) === getKey(newItems[newEnd]); end--, newEnd--) {
+                    temp[newEnd] = mapped[end];
+                    tempIndexes[newEnd] = indexes[end];
+                }
+                for (j = newEnd; j >= start; j--) {
+                    item = newItems[j];
+                    key = getKey(item);
+                    i = newIndices.get(key);
+                    newIndicesNext[j] = i === undefined ? -1 : i;
+                    newIndices.set(key, j);
+                }
+                for (i = start; i <= end; i++) {
+                    item = items[i];
+                    key = getKey(item);
+                    j = newIndices.get(key);
+                    if (j !== undefined && j !== -1) {
+                        temp[j] = mapped[i];
+                        tempIndexes[j] = indexes[i];
+                        j = newIndicesNext[j];
+                        newIndices.set(key, j);
+                    }
+                    else {
+                        if (options.onDestroy)
+                            options.onDestroy(mapped[i]);
+                    }
+                }
+                // 2) Set all new values
+                for (j = start; j < newLen; j++) {
+                    if (temp[j] !== undefined) {
+                        newMapped[j] = temp[j];
+                        newIndexes[j] = tempIndexes[j];
+                        newIndexes[j].set(j);
+                    }
+                    else {
+                        const indexSignal = signal(j);
+                        newIndexes[j] = indexSignal;
+                        newMapped[j] = mapFn(newItems[j], indexSignal);
+                    }
+                }
+                items.length = newLen;
+                for (let k = 0; k < newLen; k++)
+                    items[k] = newItems[k];
+            }
+            mapped = newMapped;
+            indexes.length = newLen;
+            for (let k = 0; k < newLen; k++)
+                indexes[k] = newIndexes[k];
+            return mapped;
+        });
+    });
+}
+
+function pooledKeys(src) {
+    const aBuf = new Set();
+    const bBuf = new Set();
+    let active = aBuf;
+    let spare = bBuf;
+    return computed(() => {
+        const val = src();
+        spare.clear();
+        for (const k in val)
+            if (Object.prototype.hasOwnProperty.call(val, k))
+                spare.add(k);
+        if (active.size === spare.size && active.isSubsetOf(spare))
+            return active;
+        const temp = active;
+        active = spare;
+        spare = temp;
+        return active;
+    });
+}
+function mapObject(source, mapFn, options = {}) {
+    const src = isSignal(source) ? source : computed(source);
+    const writable = (isWritableSignal(src)
+        ? src
+        : toWritable(src, () => {
+            // noop
+        })); // maximal overload internally
+    return linkedSignal({
+        source: pooledKeys(src),
+        computation: (next, prev) => {
+            const nextObj = {};
+            for (const k of next)
+                nextObj[k] =
+                    prev && prev.source.has(k)
+                        ? prev.value[k]
+                        : mapFn(k, derived(writable, k));
+            if (options.onDestroy && prev && prev.source.size)
+                for (const k of prev.source)
+                    if (!next.has(k))
+                        options.onDestroy(prev.value[k]);
+            return nextObj;
+        },
+    }).asReadonly();
+}
+
+/** Project with optional equality. Pure & sync. */
+const select = (projector, opt) => (src) => computed(() => projector(src()), opt);
+/** Combine with another signal using a projector. */
+const combineWith = (other, project, opt) => (src) => computed(() => project(src(), other()), opt);
+/** Only re-emit when equal(prev, next) is false. */
+const distinct = (equal = Object.is) => (src) => computed(() => src(), { equal });
+/** map to new value */
+const map = (fn) => (src) => computed(() => fn(src()));
+/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+const filter = (predicate) => (src) => linkedSignal({
+    source: src,
+    computation: (next, prev) => {
+        if (predicate(next))
+            return next;
+        return prev?.source;
+    },
+});
+/** tap into the value */
+const tap = (fn) => (src) => {
+    effect(() => fn(src()));
+    return src;
+};
+
+/**
+ * Decorate any `Signal<T>` with a chainable `.pipe(...)` method.
+ *
+ * @example
+ * const s = pipeable(signal(1)); // WritableSignal<number> (+ pipe)
+ * const label = s.pipe(n => n * 2, n => `#${n}`); // Signal<string> (+ pipe)
+ * label(); // "#2"
+ */
+function pipeable(signal) {
+    const internal = signal;
+    const mapImpl = (...fns) => {
+        const last = fns.at(-1);
+        let opt;
+        if (last && typeof last !== 'function') {
+            fns = fns.slice(0, -1);
+            opt = last;
+        }
+        if (fns.length === 0)
+            return internal;
+        if (fns.length === 1) {
+            const fn = fns[0];
+            return pipeable(computed(() => fn(internal()), opt));
+        }
+        const transformer = (input) => fns.reduce((acc, fn) => fn(acc), input);
+        return pipeable(computed(() => transformer(internal()), opt));
+    };
+    const pipeImpl = (...ops) => {
+        if (ops.length === 0)
+            return internal;
+        return ops.reduce((src, op) => pipeable(op(src)), internal);
+    };
+    Object.defineProperties(internal, {
+        map: {
+            value: mapImpl,
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        },
+        pipe: {
+            value: pipeImpl,
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        },
+    });
+    return internal;
+}
+/**
+ * Create a new **writable** signal and return it as a `PipableSignal`.
+ *
+ * The returned value is a `WritableSignal<T>` with `.set`, `.update`, `.asReadonly`
+ * still available (via intersection type), plus a chainable `.pipe(...)`.
+ *
+ * @example
+ * const count = piped(1); // WritableSignal<number> (+ pipe)
+ * const even = count.pipe(n => n % 2 === 0); // Signal<boolean> (+ pipe)
+ * count.update(n => n + 1);
+ */
+function piped(initial, opt) {
+    return pipeable(signal(initial, opt));
+}
+
+function observerSupported$1() {
+    return typeof ResizeObserver !== 'undefined';
+}
+/**
+ * Creates a read-only signal that tracks the size of a target DOM element.
+ *
+ * By default, it observes the `border-box` size to align with `getBoundingClientRect()`,
+ * which is used to provide a synchronous initial value if possible.
+ *
+ * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
+ * @param options Optional configuration including `box` (defaults to 'border-box') and `debugName`.
+ * @returns A `Signal<ElementSize | undefined>`.
+ *
+ * @example
+ * ```ts
+ * const size = elementSize(elementRef);
+ * effect(() => {
+ *   console.log('Size:', size()?.width, size()?.height);
+ * });
+ * ```
+ */
+function elementSize(target = inject(ElementRef), opt) {
+    const getElement = () => {
+        if (isSignal(target)) {
+            try {
+                const val = target();
+                return val instanceof ElementRef ? val.nativeElement : val;
+            }
+            catch {
+                return null;
+            }
+        }
+        return target instanceof ElementRef ? target.nativeElement : target;
+    };
+    const resolveInitialValue = () => {
+        if (!observerSupported$1())
+            return undefined;
+        const el = getElement();
+        if (el && el.getBoundingClientRect) {
+            const rect = el.getBoundingClientRect();
+            return { width: rect.width, height: rect.height };
+        }
+        return undefined;
+    };
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        return computed(() => untracked(resolveInitialValue), {
+            debugName: opt?.debugName,
+        });
+    }
+    const state = signal(untracked(resolveInitialValue), {
+        debugName: opt?.debugName,
+        equal: (a, b) => a?.width === b?.width && a?.height === b?.height,
+    });
+    const targetSignal = isSignal(target) ? target : computed(() => target);
+    effect((cleanup) => {
+        const el = targetSignal();
+        if (el) {
+            const nativeEl = el instanceof ElementRef ? el.nativeElement : el;
+            const rect = nativeEl.getBoundingClientRect();
+            untracked(() => state.set({ width: rect.width, height: rect.height }));
+        }
+        else {
+            untracked(() => state.set(undefined));
+            return;
+        }
+        if (!observerSupported$1())
+            return;
+        let observer = null;
+        observer = new ResizeObserver(([entry]) => {
+            let width = 0;
+            let height = 0;
+            const boxOption = opt?.box ?? 'border-box';
+            if (boxOption === 'border-box' && entry.borderBoxSize?.length > 0) {
+                const size = entry.borderBoxSize[0];
+                width = size.inlineSize;
+                height = size.blockSize;
+            }
+            else if (boxOption === 'content-box' &&
+                entry.contentBoxSize?.length > 0) {
+                width = entry.contentBoxSize[0].inlineSize;
+                height = entry.contentBoxSize[0].blockSize;
+            }
+            else {
+                width = entry.contentRect.width;
+                height = entry.contentRect.height;
+            }
+            state.set({ width, height });
+        });
+        observer.observe(el instanceof ElementRef ? el.nativeElement : el, {
+            box: opt?.box ?? 'border-box',
+        });
+        cleanup(() => {
+            observer?.disconnect();
+        });
+    });
+    return state.asReadonly();
+}
+
 function observerSupported() {
     return typeof IntersectionObserver !== 'undefined';
 }
@@ -257,7 +992,7 @@ function observerSupported() {
  * }
  * ```
  */
-function elementVisibility(target, opt) {
+function elementVisibility(target = inject(ElementRef), opt) {
     if (isPlatformServer(inject(PLATFORM_ID)) || !observerSupported()) {
         const base = computed(() => undefined, {
             debugName: opt?.debugName,
@@ -303,141 +1038,6 @@ function elementVisibility(target, opt) {
     return base;
 }
 
-/**
- * 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.
- */
-function mapArray(source, map, opt) {
-    const data = isSignal(source) ? source : computed(source);
-    const len = computed(() => data().length);
-    return linkedSignal({
-        source: () => len(),
-        computation: (len, prev) => {
-            if (!prev)
-                return Array.from({ length: len }, (_, i) => map(computed(() => source()[i], opt), i));
-            if (len === prev.value.length)
-                return prev.value;
-            if (len < prev.value.length) {
-                return prev.value.slice(0, len);
-            }
-            else {
-                const next = [...prev.value];
-                for (let i = prev.value.length; i < len; i++) {
-                    next[i] = map(computed(() => source()[i], opt), i);
-                }
-                return next;
-            }
-        },
-        equal: (a, b) => a.length === b.length,
-    });
-}
-
-const { is } = Object;
-function mutable(initial, opt) {
-    const baseEqual = opt?.equal ?? is;
-    let trigger = false;
-    const equal = (a, b) => {
-        if (trigger)
-            return false;
-        return baseEqual(a, b);
-    };
-    const sig = signal(initial, {
-        ...opt,
-        equal,
-    });
-    const internalUpdate = sig.update;
-    sig.mutate = (updater) => {
-        trigger = true;
-        internalUpdate(updater);
-        trigger = false;
-    };
-    sig.inline = (updater) => {
-        sig.mutate((prev) => {
-            updater(prev);
-            return prev;
-        });
-    };
-    return sig;
-}
-/**
- * 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.
- * }
- */
-function isMutable(value) {
-    return 'mutate' in value && typeof value.mutate === 'function';
-}
-
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -482,11 +1082,11 @@ function isMutable(value) {
  * }
  * ```
  */
-function mediaQuery(query, debugName) {
+function mediaQuery(query, debugName = 'mediaQuery') {
     if (isPlatformServer(inject(PLATFORM_ID)))
         return computed(() => false, { debugName });
     const mediaQueryList = window.matchMedia(query);
-    const state = signal(mediaQueryList.matches, { debugName });
+    const state = signal(mediaQueryList.matches, { debugName: debugName });
     const handleChange = (event) => {
         state.set(event.matches);
     };
@@ -609,8 +1209,7 @@ function throttle(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (updateSourceAction) => {
-        updateSourceAction();
+    const tick = () => {
         if (timeout)
             return;
         timeout = setTimeout(() => {
@@ -619,10 +1218,12 @@ function throttle(source, opt) {
         }, ms);
     };
     const set = (value) => {
-        triggerFn(() => source.set(value));
+        source.set(value);
+        tick();
     };
     const update = (fn) => {
-        triggerFn(() => source.update(fn));
+        source.update(fn);
+        tick();
     };
     const writable = toWritable(computed(() => {
         trigger();
@@ -670,12 +1271,12 @@ function mousePosition(opt) {
             x: 0,
             y: 0,
         }), {
-            debugName: opt?.debugName,
+            debugName: opt?.debugName ?? 'mousePosition',
         });
         base.unthrottled = base;
         return base;
     }
-    const { target = window, coordinateSpace = 'client', touch = false, debugName, throttle = 100, } = opt ?? {};
+    const { target = window, coordinateSpace = 'client', touch = false, debugName = 'mousePosition', throttle = 100, } = opt ?? {};
     const eventTarget = target instanceof ElementRef ? target.nativeElement : target;
     if (!eventTarget) {
         if (isDevMode())
@@ -736,7 +1337,7 @@ const serverDate = new Date();
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
  */
-function networkStatus(debugName) {
+function networkStatus(debugName = 'networkStatus') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const sig = computed(() => true, {
             debugName,
@@ -803,7 +1404,7 @@ function networkStatus(debugName) {
  * }
  * ```
  */
-function pageVisibility(debugName) {
+function pageVisibility(debugName = 'pageVisibility') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         return computed(() => 'visible', { debugName });
     }
@@ -865,12 +1466,12 @@ function scrollPosition(opt) {
             x: 0,
             y: 0,
         }), {
-            debugName: opt?.debugName,
+            debugName: opt?.debugName ?? 'scrollPosition',
         });
         base.unthrottled = base;
         return base;
     }
-    const { target = window, throttle = 100, debugName } = opt || {};
+    const { target = window, throttle = 100, debugName = 'scrollPosition', } = opt || {};
     let element;
     let getScrollPosition;
     if (target instanceof Window) {
@@ -956,12 +1557,12 @@ function windowSize(opt) {
         const base = computed(() => ({
             width: 1024,
             height: 768,
-        }), { debugName: opt?.debugName });
+        }), { debugName: opt?.debugName ?? 'windowSize' });
         base.unthrottled = base;
         return base;
     }
     const sizeSignal = throttled({ width: window.innerWidth, height: window.innerHeight }, {
-        debugName: opt?.debugName,
+        debugName: opt?.debugName ?? 'windowSize',
         equal: (a, b) => a.width === b.width && a.height === b.height,
         ms: opt?.throttle ?? 100,
     });
@@ -990,18 +1591,303 @@ function sensor(type, options) {
             return networkStatus(options?.debugName);
         case 'pageVisibility':
             return pageVisibility(options?.debugName);
+        case 'darkMode':
         case 'dark-mode':
             return prefersDarkMode(options?.debugName);
+        case 'reducedMotion':
         case 'reduced-motion':
             return prefersReducedMotion(options?.debugName);
+        case 'mediaQuery': {
+            const opt = options;
+            return mediaQuery(opt.query, opt.debugName);
+        }
         case 'windowSize':
             return windowSize(options);
         case 'scrollPosition':
             return scrollPosition(options);
+        case 'elementVisibility': {
+            const opt = options;
+            return elementVisibility(opt.target, opt);
+        }
+        case 'elementSize': {
+            const opt = options;
+            return elementSize(opt.target, opt);
+        }
         default:
             throw new Error(`Unknown sensor type: ${type}`);
     }
 }
+function sensors(track, opt) {
+    return track.reduce((result, key) => {
+        result[key] = sensor(key, opt?.[key]);
+        return result;
+    }, {});
+}
+
+const IS_STORE = Symbol('MMSTACK::IS_STORE');
+const PROXY_CACHE = new WeakMap();
+const SIGNAL_FN_PROP = new Set([
+    'set',
+    'update',
+    'mutate',
+    'inline',
+    'asReadonly',
+]);
+const PROXY_CLEANUP = new FinalizationRegistry(({ target, prop }) => {
+    const storeCache = PROXY_CACHE.get(target);
+    if (storeCache)
+        storeCache.delete(prop);
+});
+/**
+ * @internal
+ * Validates whether a value is a Signal Store.
+ */
+function isStore(value) {
+    return (typeof value === 'function' &&
+        value !== null &&
+        value[IS_STORE] === true);
+}
+function isIndexProp(prop) {
+    return typeof prop === 'string' && prop.trim() !== '' && !isNaN(+prop);
+}
+function isRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * @internal
+ * Makes an array store
+ */
+function toArrayStore(source, injector) {
+    if (isStore(source))
+        return source;
+    const isMutableSource = isMutable(source);
+    const lengthSignal = computed(() => {
+        const v = source();
+        if (!Array.isArray(v))
+            return 0;
+        return v.length;
+    });
+    return new Proxy(source, {
+        has(_, prop) {
+            if (prop === 'length')
+                return true;
+            if (isIndexProp(prop)) {
+                const idx = +prop;
+                return idx >= 0 && idx < untracked(lengthSignal);
+            }
+            return Reflect.has(untracked(source), prop);
+        },
+        ownKeys() {
+            const v = untracked(source);
+            if (!Array.isArray(v))
+                return [];
+            const len = v.length;
+            const arr = new Array(len + 1);
+            for (let i = 0; i < len; i++) {
+                arr[i] = String(i);
+            }
+            arr[len] = 'length';
+            return arr;
+        },
+        getPrototypeOf() {
+            return Array.prototype;
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            const v = untracked(source);
+            if (!Array.isArray(v))
+                return;
+            if (prop === 'length' ||
+                (typeof prop === 'string' && !isNaN(+prop) && +prop < v.length)) {
+                return {
+                    enumerable: true,
+                    configurable: true, // Required for proxies to dynamic targets
+                };
+            }
+            return;
+        },
+        get(target, prop, receiver) {
+            if (prop === IS_STORE)
+                return true;
+            if (prop === 'length')
+                return lengthSignal;
+            if (prop === Symbol.iterator) {
+                return function* () {
+                    for (let i = 0; i < untracked(lengthSignal); i++) {
+                        yield receiver[i];
+                    }
+                };
+            }
+            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
+                return target[prop];
+            if (isIndexProp(prop)) {
+                const idx = +prop;
+                let storeCache = PROXY_CACHE.get(target);
+                if (!storeCache) {
+                    storeCache = new Map();
+                    PROXY_CACHE.set(target, storeCache);
+                }
+                const cachedRef = storeCache.get(idx);
+                if (cachedRef) {
+                    const cached = cachedRef.deref();
+                    if (cached)
+                        return cached;
+                    storeCache.delete(idx);
+                    PROXY_CLEANUP.unregister(cachedRef);
+                }
+                const value = untracked(target);
+                const valueIsArray = Array.isArray(value);
+                const valueIsRecord = isRecord(value);
+                const equalFn = (valueIsRecord || valueIsArray) &&
+                    isMutableSource &&
+                    typeof value[idx] === 'object'
+                    ? () => false
+                    : undefined;
+                const computation = valueIsRecord
+                    ? derived(target, idx, { equal: equalFn })
+                    : derived(target, {
+                        from: (v) => v?.[idx],
+                        onChange: (newValue) => target.update((v) => {
+                            if (v === null || v === undefined)
+                                return v;
+                            try {
+                                v[idx] = newValue;
+                            }
+                            catch (e) {
+                                if (isDevMode())
+                                    console.error(`[store] Failed to set property "${String(idx)}"`, e);
+                            }
+                            return v;
+                        }),
+                    });
+                const proxy = Array.isArray(untracked(computation))
+                    ? toArrayStore(computation, injector)
+                    : toStore(computation, injector);
+                const ref = new WeakRef(proxy);
+                storeCache.set(idx, ref);
+                PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
+                return proxy;
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Converts a Signal into a deep-observable Store.
+ * Accessing nested properties returns a derived Signal of that path.
+ * @example
+ * const state = store({ user: { name: 'John' } });
+ * const nameSignal = state.user.name; // WritableSignal<string>
+ */
+function toStore(source, injector) {
+    if (isStore(source))
+        return source;
+    if (!injector)
+        injector = inject(Injector);
+    const writableSource = isWritableSignal(source)
+        ? source
+        : toWritable(source, () => {
+            // noop
+        });
+    const isMutableSource = isMutable(writableSource);
+    const s = new Proxy(writableSource, {
+        has(_, prop) {
+            return Reflect.has(untracked(source), prop);
+        },
+        ownKeys() {
+            const v = untracked(source);
+            if (!isRecord(v))
+                return [];
+            return Reflect.ownKeys(v);
+        },
+        getPrototypeOf() {
+            return Object.getPrototypeOf(untracked(source));
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            const value = untracked(source);
+            if (!isRecord(value) || !(prop in value))
+                return;
+            return {
+                enumerable: true,
+                configurable: true,
+            };
+        },
+        get(target, prop) {
+            if (prop === IS_STORE)
+                return true;
+            if (prop === 'asReadonlyStore')
+                return () => {
+                    if (!isWritableSignal(source))
+                        return s;
+                    return untracked(() => toStore(source.asReadonly(), injector));
+                };
+            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
+                return target[prop];
+            let storeCache = PROXY_CACHE.get(target);
+            if (!storeCache) {
+                storeCache = new Map();
+                PROXY_CACHE.set(target, storeCache);
+            }
+            const cachedRef = storeCache.get(prop);
+            if (cachedRef) {
+                const cached = cachedRef.deref();
+                if (cached)
+                    return cached;
+                storeCache.delete(prop);
+                PROXY_CLEANUP.unregister(cachedRef);
+            }
+            const value = untracked(target);
+            const valueIsRecord = isRecord(value);
+            const valueIsArray = Array.isArray(value);
+            const equalFn = (valueIsRecord || valueIsArray) &&
+                isMutableSource &&
+                typeof value[prop] === 'object'
+                ? () => false
+                : undefined;
+            const computation = valueIsRecord
+                ? derived(target, prop, { equal: equalFn })
+                : derived(target, {
+                    from: (v) => v?.[prop],
+                    onChange: (newValue) => target.update((v) => {
+                        if (v === null || v === undefined)
+                            return v;
+                        try {
+                            v[prop] = newValue;
+                        }
+                        catch (e) {
+                            if (isDevMode())
+                                console.error(`[store] Failed to set property "${String(prop)}"`, e);
+                        }
+                        return v;
+                    }),
+                });
+            const proxy = Array.isArray(untracked(computation))
+                ? toArrayStore(computation, injector)
+                : toStore(computation, injector);
+            const ref = new WeakRef(proxy);
+            storeCache.set(prop, ref);
+            PROXY_CLEANUP.register(proxy, { target, prop }, ref);
+            return proxy;
+        },
+    });
+    return s;
+}
+/**
+ * Creates a WritableSignalStore from a value.
+ * @see {@link toStore}
+ */
+function store(value, opt) {
+    return toStore(signal(value, opt), opt?.injector);
+}
+/**
+ * Creates a MutableSignalStore from a value.
+ * @see {@link toStore}
+ */
+function mutableStore(value, opt) {
+    return toStore(mutable(value, opt), opt?.injector);
+}
 
 // Internal dummy store for server-side rendering
 const noopStore = {
@@ -1064,7 +1950,7 @@ const noopStore = {
  * }
  * ```
  */
-function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, ...rest }) {
+function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, validate = () => true, ...rest }) {
     const isServer = isPlatformServer(inject(PLATFORM_ID));
     const fallbackStore = isServer ? noopStore : localStorage;
     const store = providedStore ?? fallbackStore;
@@ -1078,7 +1964,10 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         if (found === null)
             return null;
         try {
-            return deserialize(found);
+            const deserialized = deserialize(found);
+            if (!validate(deserialized))
+                return null;
+            return deserialized;
         }
         catch (err) {
             if (isDevMode())
@@ -1128,15 +2017,16 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     else {
         effect(() => {
             const k = keySig();
+            const internalValue = internal();
             if (k === prevKey) {
-                return storeValue(k, internal()); // normal operation
+                return storeValue(k, internalValue); // normal operation
             }
             else {
                 if (cleanupOldKey)
                     store.removeItem(prevKey);
                 const value = getValue(k);
-                internal.set(value); // load new value
                 prevKey = k;
+                internal.set(value); // load new value
             }
         });
     }
@@ -1161,41 +2051,122 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
+class MessageBus {
+    channel = new BroadcastChannel('mmstack-tab-sync-bus');
+    listeners = new Map();
+    subscribe(id, listener) {
+        this.unsubscribe(id); // Ensure no duplicate listeners
+        const wrapped = (ev) => {
+            try {
+                if (ev.data?.id === id)
+                    listener(ev.data?.value);
+            }
+            catch {
+                // noop
+            }
+        };
+        this.channel.addEventListener('message', wrapped);
+        this.listeners.set(id, wrapped);
+        return {
+            unsub: (() => this.unsubscribe(id)).bind(this),
+            post: ((value) => this.channel.postMessage({ id, value })).bind(this),
+        };
+    }
+    unsubscribe(id) {
+        const listener = this.listeners.get(id);
+        if (!listener)
+            return;
+        this.channel.removeEventListener('message', listener);
+        this.listeners.delete(id);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MessageBus, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MessageBus, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+function generateDeterministicID() {
+    const stack = new Error().stack;
+    if (stack) {
+        // Look for the actual caller (first non-internal frame)
+        const lines = stack.split('\n');
+        for (let i = 2; i < lines.length; i++) {
+            const line = lines[i];
+            if (line && !line.includes('tabSync') && !line.includes('MessageBus')) {
+                let hash = 0;
+                for (let j = 0; j < line.length; j++) {
+                    const char = line.charCodeAt(j);
+                    hash = (hash << 5) - hash + char;
+                    hash = hash & hash;
+                }
+                return `auto-${Math.abs(hash)}`;
+            }
+        }
+    }
+    throw new Error('Could not generate deterministic ID, please provide one manually.');
+}
 /**
- * Creates a Promise that resolves when a signal's value satisfies a given predicate.
+ * Synchronizes a WritableSignal across browser tabs using BroadcastChannel API.
  *
- * This is useful for imperatively waiting for a reactive state to change,
- * for example, in tests or to orchestrate complex asynchronous operations.
+ * Creates a shared signal that automatically syncs its value between all tabs
+ * of the same application. When the signal is updated in one tab, all other
+ * tabs will receive the new value automatically.
  *
- * @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.
+ * @template T - The type of the WritableSignal
+ * @param sig - The WritableSignal to synchronize across tabs
+ * @param opt - Optional configuration object
+ * @param opt.id - Explicit channel ID for synchronization. If not provided,
+ *                 a deterministic ID is generated based on the call site.
+ *                 Use explicit IDs in production for reliability.
+ *
+ * @returns The same WritableSignal instance, now synchronized across tabs
+ *
+ * @throws {Error} When deterministic ID generation fails and no explicit ID is provided
  *
  * @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."
- * }
- * }
+ * ```typescript
+ * // Basic usage - auto-generates channel ID from call site
+ * const theme = tabSync(signal('dark'));
  *
- * // Simulate updates
- * setTimeout(() => count.set(1), 500);
- * setTimeout(() => count.set(2), 1000);
- * setTimeout(() => count.set(3), 1500);
+ * // With explicit ID (recommended for production)
+ * const userPrefs = tabSync(signal({ lang: 'en' }), { id: 'user-preferences' });
  *
- * waitForCount();
+ * // Changes in one tab will sync to all other tabs
+ * theme.set('light'); // All tabs will update to 'light'
  * ```
+ *
+ * @remarks
+ * - Only works in browser environments (returns original signal on server)
+ * - Uses a single BroadcastChannel for all synchronized signals
+ * - Automatically cleans up listeners when the injection context is destroyed
+ * - Initial signal value after sync setup is not broadcasted to prevent loops
+ *
  */
+function tabSync(sig, opt) {
+    if (isPlatformServer(inject(PLATFORM_ID)))
+        return sig;
+    const id = opt?.id || generateDeterministicID();
+    const bus = inject(MessageBus);
+    const { unsub, post } = bus.subscribe(id, (next) => sig.set(next));
+    let first = false;
+    const effectRef = effect(() => {
+        const val = sig();
+        if (!first) {
+            first = true;
+            return;
+        }
+        post(val);
+    });
+    inject(DestroyRef).onDestroy(() => {
+        effectRef.destroy();
+        unsub();
+    });
+    return sig;
+}
+
 function until(sourceSignal, predicate, options = {}) {
     const injector = options.injector ?? inject(Injector);
     return new Promise((resolve, reject) => {
@@ -1351,6 +2322,8 @@ function withHistory(source, opt) {
             return;
         const valueForRedo = untracked(source);
         const valueToRestore = historyStack.at(-1);
+        if (valueToRestore === undefined)
+            return;
         originalSet.call(source, valueToRestore);
         history.inline((h) => h.pop());
         redoArray.inline((r) => r.push(valueForRedo));
@@ -1361,6 +2334,8 @@ function withHistory(source, opt) {
             return;
         const valueForUndo = untracked(source);
         const valueToRestore = redoStack.at(-1);
+        if (valueToRestore === undefined)
+            return;
         originalSet.call(source, valueToRestore);
         redoArray.inline((r) => r.pop());
         history.mutate((h) => {
@@ -1390,5 +2365,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-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 { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map