@mmstack/primitives 22.1.1 → 22.2.0

package/fesm2022/mmstack-primitives.mjs

@@ -80,7 +80,7 @@ function popFrame() {
  * ]);
  *
  * // The fine-grained mapped list
- * const mappedUsers = mapArray(
+ * const mappedUsers = indexArray(
  *   users,
  *   (userSignal, index) => {
  *     // 1. Create a fine-grained SIDE EFFECT for *this item*
@@ -101,7 +101,7 @@ function popFrame() {
  *     };
  *   },
  *   {
- *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     // 3. Tell indexArray 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();
  *     }
@@ -158,7 +158,7 @@ function nestedEffect(effectFn, options) {
 /**
  * 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`.
+ * 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 `delay`.
  *
  * @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.
@@ -167,16 +167,23 @@ function nestedEffect(effectFn, options) {
  *
  * @example
  * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
- * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ * const chunkedList = chunked(largeList, { chunkSize: 100, delay: 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);
-        };
+        delayFn =
+            typeof requestAnimationFrame === 'function'
+                ? (callback) => {
+                    const num = requestAnimationFrame(callback);
+                    return () => cancelAnimationFrame(num);
+                }
+                : // SSR: no requestAnimationFrame — approximate a frame with a timeout
+                    (cb) => {
+                        const num = setTimeout(cb, 16);
+                        return () => clearTimeout(num);
+                    };
     }
     else if (delay === 'microtask') {
         delayFn = (cb) => {
@@ -263,7 +270,9 @@ class MmActivity {
             });
         }
         for (const node of this.view.rootNodes) {
-            if (node instanceof HTMLElement)
+            // covers HTML and SVG roots; text/comment roots can't be styled — their CD is still
+            // detached, but prefer an element root for true visual hiding
+            if (node instanceof HTMLElement || node instanceof SVGElement)
                 node.style.display = visible ? '' : 'none';
         }
         if (visible)
@@ -271,10 +280,10 @@ class MmActivity {
         else
             this.view.detach();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.0", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MmActivity, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmActivity, decorators: [{
             type: Directive,
             args: [{
                     selector: '[mmActivity]',
@@ -342,14 +351,25 @@ function resolvePause(opt) {
     if (pause === false)
         return null;
     const run = (fn) => opt?.injector ? runInInjectionContext(opt.injector, fn) : fn();
+    // `inject` requires an injection context even with `optional: true`. A bare
+    // `pausableSignal(0)` (documented as "like `signal`") must degrade to the unwrapped
+    // primitive outside DI, not throw NG0203 — so injection failures fall back gracefully.
+    const tryRun = (fn, fallback) => {
+        try {
+            return run(fn);
+        }
+        catch {
+            return fallback;
+        }
+    };
     const onServer = () => typeof pause === 'function' && !opt?.injector
         ? typeof globalThis.window === 'undefined'
-        : run(() => isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser'));
+        : tryRun(() => isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser'), typeof globalThis.window === 'undefined');
     if (typeof pause === 'function')
         return onServer() ? null : pause;
     if (onServer())
         return null;
-    const paused = run(() => inject(PAUSED_CONTEXT, { optional: true }));
+    const paused = tryRun(() => inject(PAUSED_CONTEXT, { optional: true }), null);
     if (!paused) {
         if (explicit === true && isDevMode())
             console.warn('[pausable] `pause: true` but no PAUSED_CONTEXT in scope — not pausing. Provide one via an ' +
@@ -378,8 +398,9 @@ function pausableEffect(effectFn, options) {
 /**
  * Like `signal`, but pausable. While paused, READS hold the last value; writes still land on the
  * underlying signal and surface on resume. Built on the `keepPrevious`/`hold` shape — a
- * `linkedSignal` gated on the pause predicate, with `set`/`update`/`asReadonly` forwarded to the
- * source signal. With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
+ * `linkedSignal` gated on the pause predicate, with `set`/`update` forwarded to the source signal.
+ * `asReadonly()` returns the held (gated) view, so both views of the signal agree while paused.
+ * With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
  * makes it a plain `signal` — no `linkedSignal` is created.
  *
  * NOTE: while paused, `set(x)` followed by a read returns the *held* (pre-pause) value, not `x` — the
@@ -396,7 +417,8 @@ function pausableSignal(initialValue, options) {
         equal: options?.equal });
     read.set = src.set;
     read.update = src.update;
-    read.asReadonly = src.asReadonly;
+    // NOTE: `asReadonly` deliberately stays the linkedSignal's own (the held view) — the
+    // source's readonly view would show live values while the signal itself shows held ones.
     return read;
 }
 /**
@@ -433,8 +455,12 @@ function mutable(initial, opt) {
     const internalUpdate = sig.update;
     sig.mutate = (updater) => {
         cnt++;
-        internalUpdate(updater);
-        cnt--;
+        try {
+            internalUpdate(updater);
+        }
+        finally {
+            cnt--;
+        }
     };
     sig.inline = (updater) => {
         sig.mutate((prev) => {
@@ -524,7 +550,7 @@ function createNoopScope() {
         hold: (value) => value,
     };
 }
-const TRANSITION_SCOPE = new InjectionToken('@mmstack/resource:transition-scope');
+const TRANSITION_SCOPE = new InjectionToken('@mmstack/primitives:transition-scope');
 /** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
 function provideTransitionScope() {
     return { provide: TRANSITION_SCOPE, useFactory: createTransitionScope };
@@ -533,12 +559,54 @@ function injectTransitionScope() {
     const scope = inject(TRANSITION_SCOPE, { optional: true });
     if (!scope) {
         if (isDevMode())
-            console.warn('[mmstack/resource] No transition scope in context — registration/tracking here is a no-op. ' +
+            console.warn('[mmstack/primitives] No transition scope in context — registration/tracking here is a no-op. ' +
                 'Use a <mm-suspense> boundary or provideTransitionScope() in an ancestor.');
         return createNoopScope();
     }
     return scope;
 }
+function createForwardingScope() {
+    const own = createTransitionScope();
+    const target = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "target" }] : /* istanbul ignore next */ []));
+    const eff = () => target() ?? own;
+    const owners = new Map();
+    return {
+        setTarget: (t) => target.set(t),
+        resources: computed(() => eff().resources()),
+        pending: computed(() => eff().pending()),
+        suspended: (type) => eff().suspended(type),
+        add: (ref, opt) => {
+            const t = untracked(target) ?? own;
+            owners.set(ref, t);
+            t.add(ref, opt);
+        },
+        remove: (ref) => {
+            const t = owners.get(ref) ?? untracked(target) ?? own;
+            t.remove(ref);
+            owners.delete(ref);
+        },
+        commit: (value) => linkedSignal({
+            source: () => ({ v: value(), settled: !eff().pending() }),
+            computation: (curr, prev) => curr.settled || prev === undefined ? curr.v : prev.value,
+        }),
+        holding: computed(() => eff().holding()),
+        beginHold: () => (untracked(target) ?? own).beginHold(),
+        endHold: () => (untracked(target) ?? own).endHold(),
+        hold: (value) => linkedSignal({
+            source: () => ({ v: value(), held: eff().holding() }),
+            computation: (curr, prev) => prev !== undefined && curr.held ? prev.value : curr.v,
+        }),
+    };
+}
+/** Provide a forwarding transition scope at a boundary (used by the transition outlet). */
+function provideForwardingTransitionScope() {
+    return { provide: TRANSITION_SCOPE, useFactory: createForwardingScope };
+}
+/** Read the transition scope reachable from `injector`, or null if none is provided there. */
+function getTransitionScope(injector) {
+    return injector.get(TRANSITION_SCOPE, null);
+}
 /**
  * Returns a register function bound to the nearest transition scope: it adds a resource
  * to the scope and removes it when the caller's injection context is destroyed. Pass any
@@ -567,6 +635,11 @@ function registerResource(res, opt) {
  *
  * Must be called in an injection context. This is the *async* generalization (Tier 2): it adds
  * no rendering cost and needs no fork — holding direct/sync readers is a separate, deferred tier.
+ *
+ * Caveat: work must go in flight by the first post-write render to be awaited. A loader that
+ * starts later (a debounced request signal, a chained/deferred resource) is not attributable to
+ * this transition — the no-async fallback will have already resolved `done`. Trigger such work
+ * eagerly inside `fn`, or coordinate it separately.
  */
 function injectStartTransition() {
     const scope = injectTransitionScope();
@@ -621,10 +694,10 @@ class SuspenseBoundaryBase {
     pending = this.scope.pending;
     suspended = computed(() => this.scope.suspended(this.type()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "suspended" }] : /* istanbul ignore next */ []));
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.0", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
             type: Directive
         }], propDecorators: { type: [{ type: i0.Input, args: [{ isSignal: true, alias: "type", required: false }] }] } });
 const SUSPENSE_TEMPLATE = `
@@ -652,10 +725,10 @@ const SUSPENSE_HOST = {
  * `provideTransitionScope()`. The common case.
  */
 class SuspenseBoundary extends SuspenseBoundaryBase {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.0", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.2", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundary, decorators: [{
             type: Component,
             args: [{ selector: 'mm-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, providers: [provideTransitionScope()], styles: [":host{display:contents}\n"] }]
         }] });
@@ -667,10 +740,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImpor
  * ancestor.
  */
 class UnscopedSuspenseBoundary extends SuspenseBoundaryBase {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.0", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.2", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
             type: Component,
             args: [{ selector: 'mm-unscoped-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, styles: [":host{display:contents}\n"] }]
         }] });
@@ -718,6 +791,11 @@ function runInTransaction(txn, fn) {
  * The writes land on LIVE state immediately (so derived variables and connector requests see the
  * new values and refetch); only the *display* is held, via `scope.hold`. Must run in an injection
  * context.
+ *
+ * Caveat: work must go in flight by the first post-write render to be part of the transaction. A
+ * loader that starts later (a debounced request signal, a chained/deferred resource) is not
+ * attributable to it — the no-async fallback will have already committed and released the hold,
+ * after which `abort()` is a no-op. Trigger such work eagerly inside `fn`.
  */
 function injectStartTransaction() {
     const scope = injectTransitionScope();
@@ -727,7 +805,15 @@ function injectStartTransaction() {
         // Hold BEFORE the writes, so the display freezes at pre-transaction values.
         scope.beginHold();
         let finished = false;
+        // eslint-disable-next-line prefer-const -- assigned in try/catch, but needs to be declared here for the `finally` block to see it
         let watcher;
+        let resolveDone;
+        const done = new Promise((resolve) => {
+            resolveDone = resolve;
+        });
+        // Every exit path funnels through here, so `done` always settles — including `abort()`
+        // and a throwing transaction body (which would otherwise leak the hold forever and
+        // freeze the boundary with no recovery).
         const finish = (restore) => {
             if (finished)
                 return;
@@ -738,27 +824,28 @@ function injectStartTransaction() {
             else
                 txn.clear();
             scope.endHold();
+            resolveDone();
         };
-        runInTransaction(txn, fn);
+        try {
+            runInTransaction(txn, fn);
+        }
+        catch (e) {
+            finish(true);
+            throw e;
+        }
         let sawPending = false;
-        const done = new Promise((resolve) => {
-            watcher = effect(() => {
-                const p = scope.pending();
-                if (p)
-                    sawPending = true;
-                if (sawPending && !p) {
-                    finish(false);
-                    resolve();
-                }
-            }, { injector });
-            // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
-            afterNextRender(() => {
-                if (!sawPending && !untracked(scope.pending)) {
-                    finish(false);
-                    resolve();
-                }
-            }, { injector });
-        });
+        watcher = effect(() => {
+            const p = scope.pending();
+            if (p)
+                sawPending = true;
+            if (sawPending && !p)
+                finish(false);
+        }, { injector });
+        // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
+        afterNextRender(() => {
+            if (!sawPending && !untracked(scope.pending))
+                finish(false);
+        }, { injector });
         return {
             pending: scope.pending,
             done,
@@ -767,6 +854,17 @@ function injectStartTransaction() {
     };
 }
 
+/**
+ * @internal
+ */
+function getSignalEquality(sig) {
+    const internal = sig[SIGNAL];
+    if (internal && typeof internal.equal === 'function') {
+        return internal.equal;
+    }
+    return Object.is; // Default equality check
+}
+
 /**
  * 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.
@@ -865,6 +963,7 @@ function debounced(initial, opt) {
  * ```
  */
 function debounce(source, opt) {
+    const eq = opt?.equal ?? getSignalEquality(source);
     const ms = opt?.ms ?? 0;
     const trigger = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "trigger" }] : /* istanbul ignore next */ []));
@@ -880,25 +979,25 @@ function debounce(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (next) => {
+    const set = (next) => {
+        const isEqual = eq(untracked(source), next);
+        if (!timeout && isEqual)
+            return; // nothing to do
         if (timeout)
-            clearTimeout(timeout);
-        source.set(next);
+            clearTimeout(timeout); // clear pending
+        if (!isEqual)
+            source.set(next);
         timeout = setTimeout(() => {
+            timeout = undefined;
             trigger.update((c) => !c);
         }, ms);
     };
-    const set = (value) => {
-        triggerFn(value);
-    };
-    const update = (fn) => {
-        triggerFn(fn(untracked(source)));
-    };
+    const update = (fn) => set(fn(untracked(source)));
     const writable = toWritable(computed(() => {
         trigger();
         return untracked(source);
     }, opt), set, update);
-    writable.original = source;
+    writable.original = source.asReadonly();
     return writable;
 }
 
@@ -1069,8 +1168,18 @@ function derived(source, optOrKey, opt) {
     if (isMutable(source)) {
         sig.mutate = (updater) => {
             cnt++;
-            sig.update(updater);
-            cnt--;
+            try {
+                sig.update(updater);
+                // The wrapped computed evaluates its `equal` lazily — at the next read, which would
+                // normally happen after `cnt` has already dropped back to 0. For a reference-stable
+                // mutation that read compares the same object to itself and the version never bumps,
+                // so dependents are never notified. Reading here, while equality is still suppressed,
+                // forces the recompute (and version bump) inside the mutate window.
+                untracked(sig);
+            }
+            finally {
+                cnt--;
+            }
         };
         sig.inline = (updater) => {
             sig.mutate((prev) => {
@@ -1126,16 +1235,43 @@ function isDerivation(sig) {
 }
 
 function keepPrevious(src, opt) {
+    const mutableSrc = isWritableSignal$2(src) && isMutable(src);
+    // For a mutable source the linkedSignal's equality must be suppressible: a forwarded
+    // `mutate` keeps the same reference, which default equality would otherwise swallow.
+    let cnt = 0;
+    const baseEqual = opt?.equal;
+    const equal = mutableSrc
+        ? (a, b) => cnt > 0 ? false : baseEqual ? baseEqual(a, b) : Object.is(a, b)
+        : baseEqual;
     const persisted = linkedSignal({ ...(ngDevMode ? { debugName: "persisted" } : /* istanbul ignore next */ {}), ...opt,
         source: () => src(),
-        computation: (next, prev) => next === undefined && prev !== undefined ? prev.value : next });
+        computation: (next, prev) => next === undefined && prev !== undefined ? prev.value : next,
+        equal });
     if (isWritableSignal$2(src)) {
         persisted.set = src.set;
         persisted.update = src.update;
-        persisted.asReadonly = src.asReadonly;
-        if (isMutable(src)) {
-            persisted.mutate = src.mutate;
-            persisted.inline = src.inline;
+        // NOTE: `asReadonly` deliberately stays the linkedSignal's own — returning the
+        // source's readonly view would reintroduce the `undefined` flashes this wrapper exists
+        // to prevent.
+        if (mutableSrc) {
+            persisted.mutate = (updater) => {
+                cnt++;
+                try {
+                    src.mutate(updater);
+                    // force the recompute while equality is suppressed, so the reference-stable
+                    // mutation bumps the wrapper's version (see derived.ts for the same pattern)
+                    untracked(persisted);
+                }
+                finally {
+                    cnt--;
+                }
+            };
+            persisted.inline = (updater) => {
+                persisted.mutate((prev) => {
+                    updater(prev);
+                    return prev;
+                });
+            };
         }
         if (isDerivation(src)) {
             persisted.from = src.from;
@@ -1193,13 +1329,18 @@ function indexArray(source, map, opt = {}) {
         : toWritable(data, () => {
             // noop
         });
+    // copy before defaulting `equal` — assigning onto `opt` would mutate a caller-owned
+    // (possibly shared/reused) options object
     if (isWritableSignal$1(data) && isMutable(data) && !opt.equal) {
-        opt.equal = (a, b) => {
-            if (typeof a !== typeof b)
-                return false;
-            if (typeof a === 'object' || typeof a === 'function')
-                return false;
-            return a === b;
+        opt = {
+            ...opt,
+            equal: (a, b) => {
+                if (typeof a !== typeof b)
+                    return false;
+                if (typeof a === 'object' || typeof a === 'function')
+                    return false;
+                return a === b;
+            },
         };
     }
     return linkedSignal({
@@ -1395,8 +1536,17 @@ function pooledKeys(src) {
         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;
+        if (active.size === spare.size) {
+            let subset = true;
+            for (const k of active) {
+                if (!spare.has(k)) {
+                    subset = false;
+                    break;
+                }
+            }
+            if (subset)
+                return active;
+        }
         const temp = active;
         active = spare;
         spare = temp;
@@ -1496,7 +1646,7 @@ const filter = (predicate) => (src) => linkedSignal({
     computation: (next, prev) => {
         if (predicate(next))
             return next;
-        return prev?.source;
+        return prev?.value;
     },
 });
 /**
@@ -1532,7 +1682,7 @@ const tap = (fn, injector) => (src) => {
  */
 const filterWith = (predicate, initial) => (src) => linkedSignal({
     source: src,
-    computation: (next, prev) => predicate(next) ? next : (prev?.value ?? initial),
+    computation: (next, prev) => predicate(next) ? next : prev ? prev.value : initial,
 });
 /**
  * Emit `initial` on the first read, then mirror the source on every subsequent
@@ -1581,7 +1731,7 @@ const pairwise = () => (src) => linkedSignal({
  */
 const scan = (reducer, seed) => (src) => linkedSignal({
     source: src,
-    computation: (next, prev) => reducer(prev?.value ?? seed, next),
+    computation: (next, prev) => reducer(prev ? prev.value : seed, next),
 });
 
 /**
@@ -1632,7 +1782,7 @@ function pipeable(signal) {
     return internal;
 }
 /**
- * Create a new **writable** signal and return it as a `PipableSignal`.
+ * Create a new **writable** signal and return it as a `PipeableSignal`.
  *
  * The returned value is a `WritableSignal<T>` with `.set`, `.update`, `.asReadonly`
  * still available (via intersection type), plus a chainable `.pipe(...)`.
@@ -1736,6 +1886,20 @@ function pooledMap(optOrComputation, signalOpt) {
     return pooled(toPooledOptions(optOrComputation, createEmptyMap, resetClearable, signalOpt));
 }
 
+/**
+ * @internal Run a sensor factory inside `injector` when provided, else in the ambient
+ * injection context. Keeps every sensor's escape hatch identical and in one place.
+ */
+function runInSensorContext(injector, fn) {
+    return injector ? runInInjectionContext(injector, fn) : fn();
+}
+/**
+ * @internal Normalize the legacy positional `debugName: string` form into {@link SensorRunOptions}.
+ */
+function coerceSensorOptions(opt) {
+    return typeof opt === 'string' ? { debugName: opt } : (opt ?? {});
+}
+
 const EVENTS = [
     'chargingchange',
     'levelchange',
@@ -1757,7 +1921,11 @@ const EVENTS = [
  * });
  * ```
  */
-function batteryStatus(debugName = 'batteryStatus') {
+function batteryStatus(opt) {
+    const { debugName = 'batteryStatus', injector } = coerceSensorOptions(opt);
+    return runInSensorContext(injector, () => createBatteryStatus(debugName));
+}
+function createBatteryStatus(debugName) {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
         typeof navigator === 'undefined' ||
         typeof navigator.getBattery !== 'function') {
@@ -1766,7 +1934,9 @@ function batteryStatus(debugName = 'batteryStatus') {
     const state = signal(null, { ...(ngDevMode ? { debugName: "state" } : /* istanbul ignore next */ {}), debugName });
     const abortController = new AbortController();
     inject(DestroyRef).onDestroy(() => abortController.abort());
-    navigator.getBattery().then((battery) => {
+    navigator
+        .getBattery()
+        .then((battery) => {
         if (abortController.signal.aborted)
             return;
         const read = () => ({
@@ -1782,6 +1952,10 @@ function batteryStatus(debugName = 'batteryStatus') {
                 signal: abortController.signal,
             });
         }
+    })
+        .catch(() => {
+        // getBattery() rejects (NotAllowedError) when the `battery` permissions-policy is
+        // disallowed, e.g. in cross-origin iframes — stay `null`, same as unsupported.
     });
     return state.asReadonly();
 }
@@ -1797,7 +1971,11 @@ function batteryStatus(debugName = 'batteryStatus') {
  * in browsers that gate it. Errors from `navigator.clipboard.readText` are
  * swallowed silently to keep the signal value stable.
  */
-function clipboard(debugName = 'clipboard') {
+function clipboard(opt) {
+    const { debugName = 'clipboard', injector } = coerceSensorOptions(opt);
+    return runInSensorContext(injector, () => createClipboard(debugName));
+}
+function createClipboard(debugName) {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
         typeof navigator === 'undefined' ||
         !navigator.clipboard) {
@@ -1849,7 +2027,13 @@ function observerSupported$1() {
  * });
  * ```
  */
-function elementSize(target = inject(ElementRef), opt) {
+function elementSize(target, opt) {
+    return runInSensorContext(opt?.injector, () => 
+    // the host-element default must resolve INSIDE the sensor context, not as a
+    // parameter default (which would run before the injector wrapper)
+    createElementSize(target ?? inject(ElementRef), opt));
+}
+function createElementSize(target, opt) {
     const getElement = () => {
         if (isSignal(target)) {
             try {
@@ -1863,8 +2047,8 @@ function elementSize(target = inject(ElementRef), opt) {
         return target instanceof ElementRef ? target.nativeElement : target;
     };
     const resolveInitialValue = () => {
-        if (!observerSupported$1())
-            return undefined;
+        // measuring needs only getBoundingClientRect — ResizeObserver support gates
+        // live updates, not the initial read
         const el = getElement();
         if (el && el.getBoundingClientRect) {
             const rect = el.getBoundingClientRect();
@@ -1984,7 +2168,13 @@ function observerSupported() {
  * }
  * ```
  */
-function elementVisibility(target = inject(ElementRef), opt) {
+function elementVisibility(target, opt) {
+    return runInSensorContext(opt?.injector, () => 
+    // the host-element default must resolve INSIDE the sensor context, not as a
+    // parameter default (which would run before the injector wrapper)
+    createElementVisibility(target ?? inject(ElementRef), opt));
+}
+function createElementVisibility(target, opt) {
     if (isPlatformServer(inject(PLATFORM_ID)) || !observerSupported()) {
         const base = computed(() => undefined, {
             debugName: opt?.debugName,
@@ -2054,11 +2244,18 @@ function unwrap$1(target) {
  * }
  * ```
  */
-function focusWithin(target = inject(ElementRef)) {
+function focusWithin(target, opt) {
+    return runInSensorContext(opt?.injector, () => 
+    // the host-element default must resolve INSIDE the sensor context, not as a
+    // parameter default (which would run before the injector wrapper)
+    createFocusWithin(target ?? inject(ElementRef), opt));
+}
+function createFocusWithin(target, opt) {
+    const debugName = opt?.debugName ?? 'focusWithin';
     if (isPlatformServer(inject(PLATFORM_ID))) {
-        return computed(() => false, { debugName: 'focusWithin' });
+        return computed(() => false, { debugName });
     }
-    const state = signal(false, { debugName: 'focusWithin' });
+    const state = signal(false, { ...(ngDevMode ? { debugName: "state" } : /* istanbul ignore next */ {}), debugName });
     const attach = (el) => {
         state.set(el.contains(document.activeElement));
         const abortController = new AbortController();
@@ -2106,6 +2303,9 @@ function focusWithin(target = inject(ElementRef)) {
  * ```
  */
 function geolocation(opt) {
+    return runInSensorContext(opt?.injector, () => createGeolocation(opt));
+}
+function createGeolocation(opt) {
     if (isPlatformServer(inject(PLATFORM_ID)) || typeof navigator === 'undefined' || !navigator.geolocation) {
         const sig = computed(() => null, {
             debugName: opt?.debugName ?? 'geolocation',
@@ -2169,6 +2369,9 @@ const serverDate$1 = new Date();
  * ```
  */
 function idle(opt) {
+    return runInSensorContext(opt?.injector, () => createIdle(opt));
+}
+function createIdle(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const sig = computed(() => false, {
             debugName: opt?.debugName ?? 'idle',
@@ -2260,7 +2463,11 @@ function idle(opt) {
  * }
  * ```
  */
-function mediaQuery(query, debugName = 'mediaQuery') {
+function mediaQuery(query, opt) {
+    const { debugName = 'mediaQuery', injector } = coerceSensorOptions(opt);
+    return runInSensorContext(injector, () => createMediaQuery(query, debugName));
+}
+function createMediaQuery(query, debugName) {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
         typeof window === 'undefined' ||
         typeof window.matchMedia !== 'function' // jsdom doesn't implement matchMedia
@@ -2298,8 +2505,8 @@ function mediaQuery(query, debugName = 'mediaQuery') {
  * });
  * ```
  */
-function prefersDarkMode(debugName) {
-    return mediaQuery('(prefers-color-scheme: dark)', debugName);
+function prefersDarkMode(opt) {
+    return mediaQuery('(prefers-color-scheme: dark)', opt);
 }
 /**
  * Creates a read-only signal that tracks the user's OS/browser preference
@@ -2326,8 +2533,8 @@ function prefersDarkMode(debugName) {
  * });
  * ```
  */
-function prefersReducedMotion(debugName) {
-    return mediaQuery('(prefers-reduced-motion: reduce)', debugName);
+function prefersReducedMotion(opt) {
+    return mediaQuery('(prefers-reduced-motion: reduce)', opt);
 }
 
 /**
@@ -2376,6 +2583,7 @@ function throttled(initial, opt) {
  * // after the 500ms cooldown.
  */
 function throttle(source, opt) {
+    const eq = opt?.equal ?? getSignalEquality(source);
     const ms = opt?.ms ?? 0;
     const leading = opt?.leading ?? false;
     const trailing = opt?.trailing ?? true;
@@ -2402,31 +2610,32 @@ function throttle(source, opt) {
                 fire();
             else
                 pendingTrailing = trailing;
-            timeout = setTimeout(() => {
+            const onWindowEnd = () => {
                 timeout = undefined;
                 if (trailing && pendingTrailing) {
                     pendingTrailing = false;
                     fire();
+                    timeout = setTimeout(onWindowEnd, ms);
                 }
-            }, ms);
+            };
+            timeout = setTimeout(onWindowEnd, ms);
             return;
         }
         if (trailing)
             pendingTrailing = true;
     };
-    const set = (value) => {
-        source.set(value);
-        tick();
-    };
-    const update = (fn) => {
-        source.update(fn);
+    const set = (next) => {
+        if (eq(untracked(source), next))
+            return;
+        source.set(next);
         tick();
     };
+    const update = (fn) => set(fn(untracked(source)));
     const writable = toWritable(computed(() => {
         trigger();
         return untracked(source);
     }, opt), set, update);
-    writable.original = source;
+    writable.original = source.asReadonly();
     return writable;
 }
 
@@ -2463,6 +2672,9 @@ function throttle(source, opt) {
  * ```
  */
 function mousePosition(opt) {
+    return runInSensorContext(opt?.injector, () => createMousePosition(opt));
+}
+function createMousePosition(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const base = computed(() => ({
             x: 0,
@@ -2474,8 +2686,12 @@ function mousePosition(opt) {
         return base;
     }
     const { target = window, coordinateSpace = 'client', touch = false, debugName = 'mousePosition', throttle = 100, } = opt ?? {};
-    const eventTarget = target instanceof ElementRef ? target.nativeElement : target;
-    if (!eventTarget) {
+    const resolve = (t) => {
+        if (!t)
+            return null;
+        return t instanceof ElementRef ? t.nativeElement : t;
+    };
+    if (!isSignal(target) && !resolve(target)) {
         if (isDevMode())
             console.warn('mousePosition: Target element not found.');
         const base = computed(() => ({
@@ -2498,7 +2714,7 @@ function mousePosition(opt) {
             x = coordinateSpace === 'page' ? event.pageX : event.clientX;
             y = coordinateSpace === 'page' ? event.pageY : event.clientY;
         }
-        else if (event.touches.length > 0) {
+        else if (event.touches?.length > 0) {
             const firstTouch = event.touches[0];
             x = coordinateSpace === 'page' ? firstTouch.pageX : firstTouch.clientX;
             y = coordinateSpace === 'page' ? firstTouch.pageY : firstTouch.clientY;
@@ -2508,16 +2724,36 @@ function mousePosition(opt) {
         }
         pos.set({ x, y });
     };
-    eventTarget.addEventListener('mousemove', updatePosition);
-    if (touch) {
-        eventTarget.addEventListener('touchmove', updatePosition);
-    }
-    inject(DestroyRef).onDestroy(() => {
-        eventTarget.removeEventListener('mousemove', updatePosition);
+    // passive: the handler never calls preventDefault, and a non-passive touchmove on
+    // window forces the browser to wait on JS before scrolling (scroll jank on touch)
+    const attach = (el) => {
+        const controller = new AbortController();
+        el.addEventListener('mousemove', updatePosition, {
+            passive: true,
+            signal: controller.signal,
+        });
         if (touch) {
-            eventTarget.removeEventListener('touchmove', updatePosition);
+            el.addEventListener('touchmove', updatePosition, {
+                passive: true,
+                signal: controller.signal,
+            });
         }
-    });
+        return () => controller.abort();
+    };
+    if (isSignal(target)) {
+        // re-attach whenever the signal resolves to a (new) element — covers viewChild
+        effect((cleanup) => {
+            const el = resolve(target());
+            if (!el)
+                return;
+            cleanup(attach(el));
+        });
+    }
+    else {
+        const el = resolve(target);
+        if (el)
+            inject(DestroyRef).onDestroy(attach(el));
+    }
     const base = pos.asReadonly();
     base.unthrottled = pos.original;
     return base;
@@ -2531,7 +2767,8 @@ const serverDate = new Date();
  * 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.
+ * @param opt Optional debug name for the signal, or a {@link SensorRunOptions} object
+ * (with an optional `injector` for creation outside an injection context).
  * @returns A `NetworkStatusSignal` instance.
  *
  * @example
@@ -2542,7 +2779,11 @@ const serverDate = new Date();
  * });
  * ```
  */
-function networkStatus(debugName = 'networkStatus') {
+function networkStatus(opt) {
+    const { debugName = 'networkStatus', injector } = coerceSensorOptions(opt);
+    return runInSensorContext(injector, () => createNetworkStatus(debugName));
+}
+function createNetworkStatus(debugName) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const sig = computed(() => true, {
             debugName,
@@ -2592,7 +2833,11 @@ const SSR_FALLBACK = {
  * });
  * ```
  */
-function orientation(debugName = 'orientation') {
+function orientation(opt) {
+    const { debugName = 'orientation', injector } = coerceSensorOptions(opt);
+    return runInSensorContext(injector, () => createOrientation(debugName));
+}
+function createOrientation(debugName) {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
         typeof screen === 'undefined' ||
         !screen.orientation) {
@@ -2619,7 +2864,8 @@ function orientation(debugName = 'orientation') {
  * 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.
+ * @param opt Optional debug name for the signal, or a {@link SensorRunOptions} object
+ * (with an optional `injector` for creation outside an injection context).
  * @returns A read-only `Signal<DocumentVisibilityState>`. On the server,
  * it returns a static signal with a value of `'visible'`.
  *
@@ -2647,7 +2893,11 @@ function orientation(debugName = 'orientation') {
  * }
  * ```
  */
-function pageVisibility(debugName = 'pageVisibility') {
+function pageVisibility(opt) {
+    const { debugName = 'pageVisibility', injector } = coerceSensorOptions(opt);
+    return runInSensorContext(injector, () => createPageVisibility(debugName));
+}
+function createPageVisibility(debugName) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         return computed(() => 'visible', { debugName });
     }
@@ -2679,31 +2929,25 @@ function pageVisibility(debugName = 'pageVisibility') {
  * 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>
- * }
+ * <p>Host Scroll: X: {{ hostScroll().x }}, Y: {{ hostScroll().y }}</p>
  * `
  * })
  * export class ScrollTrackerComponent {
  * readonly windowScroll = scrollPosition(); // Defaults to window
+ * // Signal targets (e.g. viewChild) attach once the element exists:
  * readonly scrollableDiv = viewChild<ElementRef<HTMLDivElement>>('scrollableDiv');
- * readonly divScroll = scrollPosition({ target: this.scrollableDiv() }); // Example with element target
+ * readonly divScroll = scrollPosition({ target: this.scrollableDiv });
  *
  * constructor() {
- * effect(() => {
- * console.log('Window scrolled to:', this.windowScroll());
- * if (this.divScroll()) {
- * console.log('Div scrolled to:', this.divScroll());
- * }
- * });
+ * effect(() => console.log('Window scrolled to:', this.windowScroll()));
  * }
  * }
  * ```
  */
 function scrollPosition(opt) {
+    return runInSensorContext(opt?.injector, () => createScrollPosition(opt));
+}
+function createScrollPosition(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const base = computed(() => ({
             x: 0,
@@ -2715,43 +2959,44 @@ function scrollPosition(opt) {
         return base;
     }
     const { target = globalThis.window, throttle = 100, debugName = 'scrollPosition', } = opt || {};
-    let element;
-    let getScrollPosition;
-    if (target === globalThis.window || target.window === target) {
-        element = target;
-        getScrollPosition = () => {
-            return {
-                x: target.scrollX ?? target.pageXOffset ?? 0,
-                y: target.scrollY ?? target.pageYOffset ?? 0,
-            };
-        };
-    }
-    else if (target instanceof ElementRef) {
-        element = target.nativeElement;
-        getScrollPosition = () => {
-            return {
-                x: target.nativeElement.scrollLeft,
-                y: target.nativeElement.scrollTop,
-            };
-        };
-    }
-    else {
-        element = target;
-        getScrollPosition = () => {
-            return {
-                x: target.scrollLeft,
-                y: target.scrollTop,
-            };
-        };
-    }
-    const state = throttled(getScrollPosition(), {
+    const resolve = (t) => {
+        if (!t)
+            return null;
+        return t instanceof ElementRef ? t.nativeElement : t;
+    };
+    const isWindow = (el) => el.window === el;
+    const readPosition = (el) => isWindow(el)
+        ? {
+            x: el.scrollX ?? el.pageXOffset ?? 0,
+            y: el.scrollY ?? el.pageYOffset ?? 0,
+        }
+        : { x: el.scrollLeft, y: el.scrollTop };
+    const initial = resolve(isSignal(target) ? untracked(target) : target);
+    const state = throttled(initial ? readPosition(initial) : { x: 0, y: 0 }, {
         debugName,
         equal: (a, b) => a.x === b.x && a.y === b.y,
         ms: throttle,
     });
-    const onScroll = () => state.set(getScrollPosition());
-    element.addEventListener('scroll', onScroll, { passive: true });
-    inject(DestroyRef).onDestroy(() => element.removeEventListener('scroll', onScroll));
+    if (isSignal(target)) {
+        // re-attach whenever the signal resolves to a (new) element — covers viewChild
+        effect((cleanup) => {
+            const el = resolve(target());
+            if (!el)
+                return;
+            state.set(readPosition(el)); // sync to the new element immediately
+            const onScroll = () => state.set(readPosition(el));
+            el.addEventListener('scroll', onScroll, { passive: true });
+            cleanup(() => el.removeEventListener('scroll', onScroll));
+        });
+    }
+    else {
+        const el = resolve(target);
+        if (el) {
+            const onScroll = () => state.set(readPosition(el));
+            el.addEventListener('scroll', onScroll, { passive: true });
+            inject(DestroyRef).onDestroy(() => el.removeEventListener('scroll', onScroll));
+        }
+    }
     const base = state.asReadonly();
     base.unthrottled = state.original;
     return base;
@@ -2799,6 +3044,9 @@ function scrollPosition(opt) {
  * ```
  */
 function windowSize(opt) {
+    return runInSensorContext(opt?.injector, () => createWindowSize(opt));
+}
+function createWindowSize(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const base = computed(() => ({
             width: 1024,
@@ -2835,17 +3083,19 @@ function sensor(type, options) {
         case 'mousePosition':
             return mousePosition(opts);
         case 'networkStatus':
-            return networkStatus(opts?.debugName);
+            return networkStatus(opts);
         case 'pageVisibility':
-            return pageVisibility(opts?.debugName);
+            return pageVisibility(opts);
         case 'darkMode':
         case 'dark-mode':
-            return prefersDarkMode(opts?.debugName);
+            return prefersDarkMode(opts);
         case 'reducedMotion':
         case 'reduced-motion':
-            return prefersReducedMotion(opts?.debugName);
+            return prefersReducedMotion(opts);
         case 'mediaQuery':
-            return mediaQuery(opts.query, opts.debugName);
+            if (typeof opts?.query !== 'string')
+                throw new Error(`sensor('mediaQuery') requires a 'query' option, e.g. sensor('mediaQuery', { query: '(min-width: 1024px)' })`);
+            return mediaQuery(opts.query, opts);
         case 'windowSize':
             return windowSize(opts);
         case 'scrollPosition':
@@ -2857,15 +3107,15 @@ function sensor(type, options) {
         case 'geolocation':
             return geolocation(opts);
         case 'clipboard':
-            return clipboard(opts?.debugName);
+            return clipboard(opts);
         case 'orientation':
-            return orientation(opts?.debugName);
+            return orientation(opts);
         case 'batteryStatus':
-            return batteryStatus(opts?.debugName);
+            return batteryStatus(opts);
         case 'idle':
             return idle(opts);
         case 'focusWithin':
-            return focusWithin(opts?.target);
+            return focusWithin(opts?.target, opts);
         default:
             throw new Error(`Unknown sensor type: ${type}`);
     }
@@ -2919,16 +3169,24 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
         else
             state.set(event);
     };
-    const { destroyRef: providedDestroyRef, ...listenerOpts } = opt ?? {};
+    const { destroyRef: providedDestroyRef, 
+    // strip non-listener keys so they don't leak into addEventListener options
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    injector: _injector, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    debugName: _debugName, ...listenerOpts } = opt ?? {};
     if (isSignal(target)) {
         const targetSig = target;
-        effect((cleanup) => {
+        const effectRef = effect((cleanup) => {
             const resolved = unwrap(targetSig());
             if (!resolved)
                 return;
             resolved.addEventListener(eventName, handler, listenerOpts);
             cleanup(() => resolved.removeEventListener(eventName, handler, listenerOpts));
-        }, { injector });
+        }, { ...(ngDevMode ? { debugName: "effectRef" } : /* istanbul ignore next */ {}), injector });
+        // honor an explicit destroyRef for signal targets too — the effect would otherwise
+        // only follow the injector's lifetime, contradicting the documented option
+        providedDestroyRef?.onDestroy(() => effectRef.destroy());
     }
     else {
         const resolved = unwrap(target);
@@ -3017,7 +3275,8 @@ function alwaysFalse() {
  * @internal Attaches a lazy, memoized leaf probe to a store node. The probe (`() => boolean`)
  * closes over the node's value signal and its (stable) vivify setting, building the backing
  * `computed` on first call so leaf-ness tracks the live value reactively without taxing every
- * node access. Idempotent.
+ * node access. Under `noUnionLeaves` the caller promises shapes never flip, so the probe is
+ * resolved once from the first sample and frozen as a constant. Idempotent.
  */
 function markAsLeaf(sig, value, vivifyEnabled, noUnionLeaves) {
     if (typeof sig[LEAF] !== 'function') {
@@ -3025,13 +3284,11 @@ function markAsLeaf(sig, value, vivifyEnabled, noUnionLeaves) {
         const probe = () => {
             if (memo)
                 return memo();
-            const v = untracked(value);
-            memo =
-                isOpaque(v) || (v == null && !vivifyEnabled) || noUnionLeaves
-                    ? isLeafValue(v, vivifyEnabled)
-                        ? alwaysTrue
-                        : alwaysFalse
-                    : computed(() => isLeafValue(value(), vivifyEnabled));
+            memo = noUnionLeaves
+                ? isLeafValue(untracked(value), vivifyEnabled)
+                    ? alwaysTrue
+                    : alwaysFalse
+                : computed(() => isLeafValue(value(), vivifyEnabled));
             return memo();
         };
         Object.defineProperty(sig, LEAF, {
@@ -3119,6 +3376,40 @@ function resolveVivify(sample, option) {
 function hasOwnKey(value, key) {
     return value != null && Object.hasOwn(value, key);
 }
+/**
+ * @internal
+ * Builds the `onChange` for the fallback (non-record container) derivation branch. For an
+ * immutable source the container is copied before the write — returning the same mutated
+ * reference would let the source's equality cut propagation (leaving child signals permanently
+ * stale) and alias the caller's original object, breaking the structural-sharing contract
+ * `forkStore` relies on. For a mutable source the write goes through `mutate`, so the chain's
+ * force-notify engages (plain `update` with the same reference would never notify).
+ */
+function createFallbackOnChange(target, prop, vivifyFn, isMutableSource) {
+    const write = (newValue) => (v) => {
+        const container = vivifyFn(v, prop);
+        if (container === null || container === undefined)
+            return container;
+        const next = isMutableSource
+            ? container
+            : Array.isArray(container)
+                ? container.slice()
+                : isRecord(container)
+                    ? { ...container }
+                    : container; // non-plain leaf (Date/class instance): legacy in-place attempt
+        try {
+            next[prop] = newValue;
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error(`[store] Failed to set property "${String(prop)}"`, e);
+        }
+        return next;
+    };
+    return isMutableSource
+        ? (newValue) => target.mutate(write(newValue))
+        : (newValue) => target.update(write(newValue));
+}
 /**
  * @internal
  * Makes an array store
@@ -3142,7 +3433,9 @@ function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
                 const idx = +prop;
                 return idx >= 0 && idx < untracked(lengthSignal);
             }
-            return Reflect.has(untracked(source), prop);
+            const v = untracked(source);
+            // nullish node values are routinely descended with vivify on — `in` must not throw
+            return v == null ? false : Reflect.has(v, prop);
         },
         ownKeys() {
             const v = untracked(source);
@@ -3179,7 +3472,9 @@ function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
                 return lengthSignal;
             if (prop === Symbol.iterator) {
                 return function* () {
-                    for (let i = 0; i < untracked(lengthSignal); i++) {
+                    // read length reactively: a spread/for-of inside a computed/effect must re-run
+                    // when items are added or removed, not only when already-read elements change
+                    for (let i = 0; i < lengthSignal(); i++) {
                         yield receiver[i];
                     }
                 };
@@ -3218,19 +3513,8 @@ function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
                     })
                     : derived(target, {
                         from: (v) => v?.[idx],
-                        onChange: (newValue) => target.update((v) => {
-                            const container = vivifyFn(v, idx);
-                            if (container === null || container === undefined)
-                                return container;
-                            try {
-                                container[idx] = newValue;
-                            }
-                            catch (e) {
-                                if (isDevMode())
-                                    console.error(`[store] Failed to set property "${String(idx)}"`, e);
-                            }
-                            return container;
-                        }),
+                        onChange: createFallbackOnChange(target, idx, vivifyFn, isMutableSource),
+                        equal: equalFn,
                     });
                 const childSample = untracked(computation);
                 const childVivify = resolveVivify(childSample, vivify);
@@ -3250,6 +3534,13 @@ function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
 /**
  * Converts a Signal into a deep-observable Store.
  * Accessing nested properties returns a derived Signal of that path.
+ *
+ * @remarks
+ * A child's *container kind* (array store vs object store) is resolved when the child is
+ * first accessed and cached with the proxy. Leaf↔substore flips are tracked reactively, but a
+ * union-typed node that later flips between an array and a record keeps its original trap set —
+ * if you need that, re-model the union as `{ kind: ..., value: ... }` instead.
+ *
  * @example
  * const state = store({ user: { name: 'John' } });
  * const nameSignal = state.user.name; // WritableSignal<string>
@@ -3332,19 +3623,8 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
                 ? derived(target, prop, { equal: equalFn, vivify: nodeVivify })
                 : derived(target, {
                     from: (v) => v?.[prop],
-                    onChange: (newValue) => target.update((v) => {
-                        const container = vivifyFn(v, prop);
-                        if (container === null || container === undefined)
-                            return container;
-                        try {
-                            container[prop] = newValue;
-                        }
-                        catch (e) {
-                            if (isDevMode())
-                                console.error(`[store] Failed to set property "${String(prop)}"`, e);
-                        }
-                        return container;
-                    }),
+                    onChange: createFallbackOnChange(target, prop, vivifyFn, isMutableSource),
+                    equal: equalFn,
                 });
             const childSample = untracked(computation);
             const childVivify = resolveVivify(childSample, vivify);
@@ -3487,7 +3767,12 @@ function merge3(ancestor, mine, theirs) {
     if (isPlainRecord(mine) && isPlainRecord(theirs) && isPlainRecord(ancestor)) {
         const out = { ...theirs };
         for (const key of new Set([...Object.keys(mine), ...Object.keys(theirs)])) {
-            out[key] = merge3(ancestor[key], mine[key], theirs[key]);
+            const merged = merge3(ancestor[key], mine[key], theirs[key]);
+            // a key deleted on the fork must commit as ABSENT, not as an explicit `undefined`
+            if (merged === undefined && !(key in mine))
+                delete out[key];
+            else
+                out[key] = merged;
         }
         return out;
     }
@@ -3539,8 +3824,8 @@ const noopStore = {
  *
  * @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.
+ * or when deserialization fails. A stored value (including a legitimate `null` for a
+ * nullable `T`) always round-trips; the fallback only surfaces when the entry is absent.
  * @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
@@ -3553,7 +3838,8 @@ const noopStore = {
  * - **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`.
+ * using `DestroyRef`. Web Storage only: the `storage` event never fires for custom `store`
+ * adapters, so `syncTabs` has no effect with one.
  * - **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.
  *
@@ -3588,25 +3874,28 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         : isSignal(key)
             ? key
             : computed(key);
+    // "no stored value" marker — distinct from `null`/`undefined`, so a nullable `T` can
+    // round-trip a legitimate `null` through `set` instead of it acting like `clear()`
+    const EMPTY = Symbol();
     const getValue = (key) => {
         const found = store.getItem(key);
         if (found === null)
-            return null;
+            return EMPTY;
         try {
             const deserialized = deserialize(found);
             if (!validate(deserialized))
-                return null;
+                return EMPTY;
             return deserialized;
         }
         catch (err) {
             if (isDevMode())
                 console.error(`Failed to parse stored value for key "${key}":`, err);
-            return null;
+            return EMPTY;
         }
     };
     const storeValue = (key, value) => {
         try {
-            if (value === null)
+            if (value === EMPTY)
                 return store.removeItem(key);
             const serialized = serialize(value);
             store.setItem(key, serialized);
@@ -3623,9 +3912,9 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     const initialKey = untracked(keySig);
     const internal = signal(getValue(initialKey), { ...(ngDevMode ? { debugName: "internal" } : /* istanbul ignore next */ {}), ...opt,
         equal: (a, b) => {
-            if (a === null && b === null)
+            if (a === EMPTY && b === EMPTY)
                 return true;
-            if (a === null || b === null)
+            if (a === EMPTY || b === EMPTY)
                 return false;
             return equal(a, b);
         } });
@@ -3660,19 +3949,27 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     if (syncTabs && !isServer) {
         const destroyRef = inject(DestroyRef);
         const sync = (e) => {
+            // `storage` events only describe Web Storage — ignore events for a different
+            // storage area (or any event when a custom adapter is configured), otherwise an
+            // unrelated localStorage write with the same key string corrupts our state
+            if (e.storageArea !== store)
+                return;
             if (e.key !== untracked(keySig))
                 return;
             if (e.newValue === null)
-                internal.set(null);
+                internal.set(EMPTY);
             else
                 internal.set(getValue(e.key));
         };
         window.addEventListener('storage', sync);
         destroyRef.onDestroy(() => window.removeEventListener('storage', sync));
     }
-    const writable = toWritable(computed(() => internal() ?? fallback, opt), internal.set);
+    const writable = toWritable(computed(() => {
+        const v = internal();
+        return v === EMPTY ? fallback : v;
+    }, opt), internal.set);
     writable.clear = () => {
-        internal.set(null);
+        internal.set(EMPTY);
     };
     writable.key = keySig;
     return writable;
@@ -3682,7 +3979,6 @@ 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)
@@ -3693,28 +3989,43 @@ class MessageBus {
             }
         };
         this.channel.addEventListener('message', wrapped);
-        this.listeners.set(id, wrapped);
+        let set = this.listeners.get(id);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(id, set);
+        }
+        set.add(wrapped);
         return {
-            unsub: (() => this.unsubscribe(id)).bind(this),
-            post: ((value) => this.channel.postMessage({ id, value })).bind(this),
+            unsub: () => {
+                this.channel.removeEventListener('message', wrapped);
+                const cur = this.listeners.get(id);
+                if (!cur)
+                    return;
+                cur.delete(wrapped);
+                if (cur.size === 0)
+                    this.listeners.delete(id);
+            },
+            post: (value) => this.channel.postMessage({ id, value }),
         };
     }
-    unsubscribe(id) {
-        const listener = this.listeners.get(id);
-        if (!listener)
-            return;
-        this.channel.removeEventListener('message', listener);
-        this.listeners.delete(id);
+    ngOnDestroy() {
+        this.channel.close();
+        this.listeners.clear();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MessageBus, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MessageBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
                 }]
         }] });
+/**
+ * @deprecated The generated id hashes the call-site stack line, which collides when a shared
+ * helper calls {@link tabSync} for multiple signals and diverges across minified builds during
+ * a rolling deploy. Pass an explicit `{ id }` instead.
+ */
 function generateDeterministicID() {
     const stack = new Error().stack;
     if (stack) {
@@ -3752,10 +4063,8 @@ function generateDeterministicID() {
  *
  * @example
  * ```typescript
- * // Basic usage - auto-generates channel ID from call site
- * const theme = tabSync(signal('dark'));
- *
- * // With explicit ID (recommended for production)
+ * // With explicit ID (recommended)
+ * const theme = tabSync(signal('dark'), { id: 'theme' });
  * const userPrefs = tabSync(signal({ lang: 'en' }), { id: 'user-preferences' });
  *
  * // Changes in one tab will sync to all other tabs
@@ -3767,6 +4076,7 @@ function generateDeterministicID() {
  * - 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
+ * - Received values are not re-broadcast, so tabs never echo each other's updates
  *
  */
 function tabSync(sig, opt) {
@@ -3774,7 +4084,20 @@ function tabSync(sig, opt) {
         return sig;
     const id = typeof opt === 'string' ? opt : (opt?.id ?? generateDeterministicID());
     const bus = inject(MessageBus);
-    const { unsub, post } = bus.subscribe(id, (next) => sig.set(next));
+    // The last value applied from a remote tab. The outbound effect skips (exactly) the run
+    // caused by that write — without this, an inbound object (a fresh structured clone, so
+    // never reference-equal) would be re-posted, and two tabs would ping-pong forever.
+    const NONE = Symbol();
+    let received = NONE;
+    const { unsub, post } = bus.subscribe(id, (next) => {
+        const before = untracked(sig);
+        received = next;
+        sig.set(next);
+        // Equality-suppressed write (e.g. an identical primitive): no effect run will follow,
+        // so clear the marker — it must not swallow a later, genuinely local change.
+        if (untracked(sig) === before)
+            received = NONE;
+    });
     let first = false;
     const effectRef = effect(() => {
         const val = sig();
@@ -3782,6 +4105,11 @@ function tabSync(sig, opt) {
             first = true;
             return;
         }
+        if (val === received) {
+            received = NONE;
+            return;
+        }
+        received = NONE;
         post(val);
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "effectRef" }] : /* istanbul ignore next */ []));
@@ -3793,7 +4121,6 @@ function tabSync(sig, opt) {
 }
 
 function until(sourceSignal, predicate, options = {}) {
-    const injector = options.injector ?? inject(Injector);
     return new Promise((resolve, reject) => {
         let effectRef;
         let timeoutId;
@@ -3830,6 +4157,14 @@ function until(sourceSignal, predicate, options = {}) {
             cleanupAndResolve(initialValue);
             return;
         }
+        let injector;
+        try {
+            injector = options.injector ?? inject(Injector);
+        }
+        catch {
+            cleanupAndReject('until: No injector available — provide options.injector when calling outside an injection context.');
+            return;
+        }
         if (options?.timeout !== undefined) {
             timeoutId = setTimeout(() => cleanupAndReject(`until: Timeout after ${options.timeout}ms.`), options.timeout);
         }
@@ -3847,17 +4182,6 @@ function until(sourceSignal, predicate, options = {}) {
     });
 }
 
-/**
- * @interal
- */
-function getSignalEquality(sig) {
-    const internal = sig[SIGNAL];
-    if (internal && typeof internal.equal === 'function') {
-        return internal.equal;
-    }
-    return Object.is; // Default equality check
-}
-
 /**
  * Enhances an existing `WritableSignal` by adding a complete undo/redo history
  * stack and an API to control it.
@@ -3906,9 +4230,10 @@ function getSignalEquality(sig) {
  * ```
  */
 function withHistory(sourceOrValue, opt) {
-    const equal = (opt?.equal ?? isSignal(sourceOrValue))
-        ? getSignalEquality(sourceOrValue)
-        : Object.is;
+    const equal = opt?.equal ??
+        (isSignal(sourceOrValue)
+            ? getSignalEquality(sourceOrValue)
+            : Object.is);
     const source = isSignal(sourceOrValue)
         ? sourceOrValue
         : signal(sourceOrValue);
@@ -3953,9 +4278,8 @@ function withHistory(sourceOrValue, opt) {
         if (historyStack.length === 0)
             return;
         const valueForRedo = untracked(source);
-        const valueToRestore = historyStack.at(-1);
-        if (valueToRestore === undefined)
-            return;
+        // length checked above — a legitimately `undefined` entry must still restore
+        const valueToRestore = historyStack[historyStack.length - 1];
         originalSet.call(source, valueToRestore);
         history.inline((h) => h.pop());
         redoArray.mutate((r) => {
@@ -3969,9 +4293,8 @@ function withHistory(sourceOrValue, opt) {
         if (redoStack.length === 0)
             return;
         const valueForUndo = untracked(source);
-        const valueToRestore = redoStack.at(-1);
-        if (valueToRestore === undefined)
-            return;
+        // length checked above — a legitimately `undefined` entry must still restore
+        const valueToRestore = redoStack[redoStack.length - 1];
         originalSet.call(source, valueToRestore);
         redoArray.inline((r) => r.pop());
         history.mutate((h) => {
@@ -3997,5 +4320,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { MmActivity, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, forkStore, geolocation, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export { MmActivity, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map