@mmstack/primitives 19.3.6 → 19.3.8

package/fesm2022/mmstack-primitives.mjs

@@ -399,37 +399,158 @@ function isMutable(value) {
     return 'mutate' in value && typeof value.mutate === 'function';
 }
 
+/**
+ * @internal
+ * Type guard for an array-index-like property key: a non-empty string that parses to a finite
+ * number (e.g. `'0'`, `'42'`). Used to choose array-vs-object shape during autovivification and
+ * deep store proxying.
+ */
+function isIndexProp(prop) {
+    return typeof prop === 'string' && prop.trim() !== '' && !isNaN(+prop);
+}
+
+// Container resolvers used by createVivify: each returns the current value when present and
+// only creates a new container when it is null/undefined.
+function identity(x) {
+    return x;
+}
+function createArray(cur) {
+    if (cur === null || cur === undefined)
+        return [];
+    return cur;
+}
+function createObject(cur) {
+    if (cur === null || cur === undefined)
+        return {};
+    return cur;
+}
+function createAuto(cur, key) {
+    if (cur === null || cur === undefined) {
+        return typeof key === 'number' || isIndexProp(key)
+            ? []
+            : {};
+    }
+    return cur;
+}
+/**
+ * @internal
+ * Resolves a {@link Vivify} option into a {@link VivifyFn}. The returned function leaves a
+ * present value untouched and only creates a new container — object, array, or factory result —
+ * when the current value is `null`/`undefined`.
+ */
+function createVivify(option) {
+    switch (option) {
+        case false:
+            return identity;
+        case 'array':
+            return createArray;
+        case 'object':
+            return createObject;
+        case 'auto':
+        case true:
+            return createAuto;
+        default:
+            return typeof option === 'function'
+                ? (cur) => cur === null || cur === undefined ? option() : cur
+                : identity;
+    }
+}
+
+function createMutableArrayUpdater(source, index, vivifyFn) {
+    return (next) => source.mutate((cur) => {
+        const vivified = vivifyFn(cur, index);
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        vivified[index] = next;
+        return vivified;
+    });
+}
+function createImmutableArrayUpdater(source, index, vivifyFn) {
+    return (next) => source.update((cur) => {
+        const vivified = vivifyFn(cur, index)?.slice();
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        vivified[index] = next;
+        return vivified;
+    });
+}
+function createMutableObjectUpdater(source, key, vivifyFn) {
+    return (next) => source.mutate((cur) => {
+        const vivified = vivifyFn(cur, key);
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        vivified[key] = next;
+        return vivified;
+    });
+}
+function createImmutableObjectUpdater(source, key, vivifyFn) {
+    return (next) => source.update((cur) => {
+        const vivified = vivifyFn(cur, key);
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        return { ...vivified, [key]: next };
+    });
+}
+function createUpdater(source, key, vivify) {
+    const sample = untracked(source);
+    // fast path for when vivification is off
+    if (!vivify) {
+        if (Array.isArray(sample) && typeof key === 'number') {
+            const idx = key;
+            return isMutable(source)
+                ? (next) => source.mutate((cur) => {
+                    cur[idx] = next;
+                    return cur;
+                })
+                : (next) => source.update((cur) => {
+                    const copy = cur.slice();
+                    copy[idx] = next;
+                    return copy;
+                });
+        }
+        return isMutable(source)
+            ? (next) => source.mutate((cur) => {
+                cur[key] = next;
+                return cur;
+            })
+            : (next) => source.update((cur) => ({
+                ...cur,
+                [key]: next,
+            }));
+    }
+    const present = sample !== null && sample !== undefined;
+    const keyIsIndex = typeof key === 'number' || isIndexProp(key);
+    let vivifyOpt = vivify;
+    if (vivifyOpt === 'auto' || vivifyOpt === true) {
+        vivifyOpt = ((present ? Array.isArray(sample) : keyIsIndex) ? 'array' : 'object');
+    }
+    const vivifyFn = createVivify(vivifyOpt);
+    // Route to the array updater whenever the container is (or will be vivified as) an
+    // array, so the updater and the created container agree on shape for a nullish source.
+    const isArray = vivifyOpt === 'array'
+        ? keyIsIndex
+        : vivifyOpt === 'object'
+            ? false
+            : Array.isArray(sample) && typeof key === 'number';
+    if (isArray)
+        return isMutable(source)
+            ? createMutableArrayUpdater(source, key, vivifyFn)
+            : createImmutableArrayUpdater(source, key, vivifyFn);
+    return isMutable(source)
+        ? createMutableObjectUpdater(source, key, vivifyFn)
+        : createImmutableObjectUpdater(source, key, vivifyFn);
+}
 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 vivify = typeof optOrKey === 'object' ? false : (opt?.vivify ?? false);
+    // With vivification the source may legitimately be null/undefined
+    const from = typeof optOrKey === 'object'
+        ? optOrKey.from
+        : vivify
+            ? (v) => v?.[optOrKey]
+            : (v) => v[optOrKey];
     const onChange = typeof optOrKey === 'object'
         ? optOrKey.onChange
-        : isArray
-            ? 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 }));
-                };
+        : createUpdater(source, optOrKey, vivify);
     const rest = typeof optOrKey === 'object' ? { ...optOrKey, ...opt } : opt;
     const baseEqual = rest?.equal ?? Object.is;
     let cnt = 0;
@@ -602,7 +723,30 @@ const mapArray = indexArray;
  * @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.
+ *  - `key`: A custom key extractor for identity matching (e.g. `(item) => item.id`)
+ *    when item references change but conceptual identity is preserved.
  * @returns A `Signal<U[]>` containing the mapped array.
+ *
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ * ]);
+ *
+ * const rows = keyArray(
+ *   users,
+ *   (user, index) => ({
+ *     label: computed(() => `#${index()} ${user.name}`),
+ *     id: user.id,
+ *   }),
+ *   { key: (u) => u.id },
+ * );
+ *
+ * // Reordering users() rebuilds index signals only — `rows` entries
+ * // are matched by id and reused, not re-created.
+ * users.set([users()[1], users()[0]]);
+ * ```
  */
 function keyArray(source, mapFn, options = {}) {
     const sourceSignal = isSignal(source) ? source : computed(source);
@@ -759,15 +903,69 @@ function mapObject(source, mapFn, options = {}) {
     }).asReadonly();
 }
 
-/** Project with optional equality. Pure & sync. */
+/**
+ * Synchronous projection of a signal value with optional `CreateSignalOptions`
+ * (custom `equal`, `debugName`, etc.). Equivalent to `map` plus the ability to
+ * pass signal options through to the underlying `computed()`.
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, name: 'Alice' });
+ * const name = user.pipe(select((u) => u.name));
+ * name(); // 'Alice'
+ * ```
+ */
 const select = (projector, opt) => (src) => computed(() => projector(src()), opt);
-/** Combine with another signal using a projector. */
+/**
+ * Combine the piped signal with another `Signal` using a projector. The result
+ * recomputes whenever either source changes.
+ *
+ * @example
+ * ```ts
+ * const price = piped(10);
+ * const quantity = signal(3);
+ * const total = price.pipe(combineWith(quantity, (p, q) => p * q));
+ * total(); // 30
+ * ```
+ */
 const combineWith = (other, project, opt) => (src) => computed(() => project(src(), other()), opt);
-/** Only re-emit when equal(prev, next) is false. */
+/**
+ * Suppress emissions while consecutive values are considered equal. The
+ * comparator defaults to `Object.is`; pass a custom one for structural or
+ * key-based equality (e.g. compare by `id` only).
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, lastSeen: Date.now() });
+ * const byId = user.pipe(distinct((a, b) => a.id === b.id));
+ * // byId only re-emits when `id` changes, not on every `lastSeen` update
+ * ```
+ */
 const distinct = (equal = Object.is) => (src) => computed(() => src(), { equal });
-/** map to new value */
+/**
+ * Pure synchronous transform from input to output. Equivalent to a `computed()`
+ * that reads the source and returns `fn(value)`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(2);
+ * const doubled = count.pipe(map((n) => n * 2));
+ * doubled(); // 4
+ * ```
+ */
 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 */
+/**
+ * Keep only values that pass the predicate. The result holds the last passing
+ * value across emissions; before any value passes, the result is `undefined` —
+ * see {@link filterWith} when you need a non-`undefined` seed.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const clicks = event.pipe(filter((e): e is MouseEvent => e?.type === 'click'));
+ * clicks(); // undefined until a click happens, then the last MouseEvent
+ * ```
+ */
 const filter = (predicate) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => {
@@ -776,7 +974,19 @@ const filter = (predicate) => (src) => linkedSignal({
         return prev?.source;
     },
 });
-/** tap into the value */
+/**
+ * Run a side effect on every emission without altering the signal value. Wraps
+ * Angular's `effect()`, so it must run in an injection context or receive an
+ * explicit `injector`. Use for logging / analytics — not for setting other
+ * signals (that's what regular `effect()` is for).
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * count.pipe(tap((n) => console.log('count:', n)));
+ * count.set(1); // logs 'count: 1'
+ * ```
+ */
 const tap = (fn, injector) => (src) => {
     effect(() => fn(src()), {
         injector,
@@ -784,24 +994,66 @@ const tap = (fn, injector) => (src) => {
     return src;
 };
 /**
- * Like {@link filter}, but emits `initial` until a value passes the predicate
- * for the first time. Avoids the `T | undefined` return type.
+ * Like {@link filter}, but emits `initial` until a value first passes the
+ * predicate. Eliminates the `T | undefined` return type at the cost of an
+ * explicit seed value.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const lastClick = event.pipe(filterWith((e) => e?.type === 'click', null));
+ * lastClick(); // null until the first click, then the most recent click event
+ * ```
  */
 const filterWith = (predicate, initial) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => predicate(next) ? next : (prev?.value ?? initial),
 });
-/** Emits `initial` first, then mirrors source. */
+/**
+ * Emit `initial` on the first read, then mirror the source on every subsequent
+ * read. Useful for giving a pipeline a sensible seed value before the source
+ * is ready (e.g. loading state).
+ *
+ * @example
+ * ```ts
+ * const data = piped<User | null>(null);
+ * const view = data.pipe(startWith<User | null, 'loading'>('loading'));
+ * view(); // 'loading' on first read, then User | null afterward
+ * ```
+ */
 const startWith = (initial) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => (prev === undefined ? initial : next),
 });
-/** Emits `[prev, curr]` pairs. The first emission has prev = undefined. */
+/**
+ * Emit `[prev, curr]` tuples so consumers can react to transitions instead of
+ * raw values. On the first emission `prev` is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * const delta = count.pipe(pairwise(), map(([prev, curr]) => curr - (prev ?? 0)));
+ * count.set(5);
+ * delta(); // 5
+ * ```
+ */
 const pairwise = () => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => [prev?.source, next],
 });
-/** Reduce-like accumulator across emissions. */
+/**
+ * Reduce-like accumulator that folds each emission into a running result.
+ * Behaves like `Array.prototype.reduce` but applied over time, with the
+ * accumulator persisted across emissions.
+ *
+ * @example
+ * ```ts
+ * const delta = piped(0);
+ * const total = delta.pipe(scan((acc, n) => acc + n, 0));
+ * delta.set(5); // total() === 5
+ * delta.set(3); // total() === 8
+ * ```
+ */
 const scan = (reducer, seed) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => reducer(prev?.value ?? seed, next),
@@ -970,6 +1222,15 @@ const EVENTS = [
  * Battery Status API. Returns `null` until the underlying `getBattery()`
  * promise resolves, or permanently when the API is unsupported (Firefox /
  * Safari at the time of writing). SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const battery = batteryStatus();
+ * effect(() => {
+ *   const b = battery();
+ *   if (b) console.log(`${Math.round(b.level * 100)}% • charging: ${b.charging}`);
+ * });
+ * ```
  */
 function batteryStatus(debugName = 'batteryStatus') {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
@@ -1252,6 +1513,15 @@ function unwrap$1(target) {
  * Defaults `target` to the current `ElementRef` so it can be used inline in a
  * component's `class` field. SSR-safe — returns a constant `false` signal on
  * the server.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MenuComponent {
+ *   // Defaults to the host element — flips true when focus is inside.
+ *   readonly hasFocus = focusWithin();
+ * }
+ * ```
  */
 function focusWithin(target = inject(ElementRef)) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1354,6 +1624,14 @@ const serverDate$1 = new Date();
  * activity) resets the timer and flips the signal back to `false`.
  *
  * SSR-safe — always `false` with a frozen `since` date on the server.
+ *
+ * @example
+ * ```ts
+ * const isAway = idle({ ms: 30_000 });
+ * effect(() => {
+ *   if (isAway()) console.log('idle since', isAway.since());
+ * });
+ * ```
  */
 function idle(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1717,6 +1995,14 @@ const serverDate = new Date();
  *
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const online = networkStatus();
+ * effect(() => {
+ *   if (!online()) console.log('offline since', online.since());
+ * });
+ * ```
  */
 function networkStatus(debugName = 'networkStatus') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1758,6 +2044,15 @@ const SSR_FALLBACK = {
  *
  * SSR-safe — returns a constant `portrait-primary / 0°` signal on the server
  * and in environments without `screen.orientation` support.
+ *
+ * @example
+ * ```ts
+ * const screenOrientation = orientation();
+ * effect(() => {
+ *   const { type, angle } = screenOrientation();
+ *   console.log(`${type} at ${angle}°`);
+ * });
+ * ```
  */
 function orientation(debugName = 'orientation') {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
@@ -2036,6 +2331,27 @@ function sensor(type, options) {
             throw new Error(`Unknown sensor type: ${type}`);
     }
 }
+/**
+ * Bulk sensor factory — creates several sensor signals at once and returns
+ * them keyed by sensor type. Convenient when a single consumer needs to react
+ * to multiple browser signals; for a single sensor prefer {@link sensor}
+ * directly.
+ *
+ * @typeParam TType The union of sensor keys being requested.
+ * @param track Array of sensor type keys to create.
+ * @param opt Optional per-sensor options keyed by sensor type.
+ * @returns A record `{ [key]: <SensorReturnType> }` for each requested key.
+ *
+ * @example
+ * ```ts
+ * const { windowSize, networkStatus } = sensors(
+ *   ['windowSize', 'networkStatus'],
+ *   { windowSize: { throttle: 200 } },
+ * );
+ *
+ * effect(() => console.log(windowSize(), networkStatus()));
+ * ```
+ */
 function sensors(track, opt) {
     return track.reduce((result, key) => {
         result[key] = sensor(key, opt?.[key]);
@@ -2087,6 +2403,12 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
 }
 
 const IS_STORE = Symbol('MMSTACK::IS_STORE');
+const SCOPE_PARENT = Symbol('MMSTACK::SCOPE_PARENT');
+/**
+ * @internal
+ * Test-only handle on the proxy cache (deliberately NOT re-exported from the public barrel).
+ * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
+ */
 const PROXY_CACHE = new WeakMap();
 const SIGNAL_FN_PROP = new Set([
     'set',
@@ -2095,6 +2417,11 @@ const SIGNAL_FN_PROP = new Set([
     'inline',
     'asReadonly',
 ]);
+/**
+ * @internal
+ * Test-only handle on the finalization registry (deliberately NOT re-exported from the public
+ * barrel). Prunes a cache entry once its proxy is reclaimed by the GC.
+ */
 const PROXY_CLEANUP = new FinalizationRegistry(({ target, prop }) => {
     const storeCache = PROXY_CACHE.get(target);
     if (storeCache)
@@ -2109,20 +2436,35 @@ function isStore(value) {
         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
+ * Resolves the vivify shape for a node from its current value: a present record/array is a
+ * certainty we keep (cached in the derivation, so it survives the value being nulled); an
+ * unknown value (`null`/`undefined`) defers to the caller's option. Off stays off.
+ */
+function resolveVivify(sample, option) {
+    if (!option)
+        return false;
+    if (Array.isArray(sample))
+        return 'array';
+    if (isRecord(sample))
+        return 'object';
+    return 'auto';
+}
+function hasOwnKey(value, key) {
+    return value != null && Object.hasOwn(value, key);
+}
 /**
  * @internal
  * Makes an array store
  */
-function toArrayStore(source, injector) {
+function toArrayStore(source, injector, vivify) {
     if (isStore(source))
         return source;
     const isMutableSource = isMutable(source);
@@ -2202,31 +2544,39 @@ function toArrayStore(source, injector) {
                 const value = untracked(target);
                 const valueIsArray = Array.isArray(value);
                 const valueIsRecord = isRecord(value);
+                const nodeVivify = resolveVivify(value, vivify);
+                const vivifyFn = createVivify(nodeVivify);
                 const equalFn = (valueIsRecord || valueIsArray) &&
                     isMutableSource &&
                     typeof value[idx] === 'object'
                     ? () => false
                     : undefined;
                 const computation = valueIsRecord
-                    ? derived(target, idx, { equal: equalFn })
+                    ? derived(target, idx, {
+                        equal: equalFn,
+                        vivify: nodeVivify,
+                    })
                     : derived(target, {
                         from: (v) => v?.[idx],
                         onChange: (newValue) => target.update((v) => {
-                            if (v === null || v === undefined)
-                                return v;
+                            const container = vivifyFn(v, idx);
+                            if (container === null || container === undefined)
+                                return container;
                             try {
-                                v[idx] = newValue;
+                                container[idx] = newValue;
                             }
                             catch (e) {
                                 if (isDevMode())
                                     console.error(`[store] Failed to set property "${String(idx)}"`, e);
                             }
-                            return v;
+                            return container;
                         }),
                     });
-                const proxy = Array.isArray(untracked(computation))
-                    ? toArrayStore(computation, injector)
-                    : toStore(computation, injector);
+                const childSample = untracked(computation);
+                const childVivify = resolveVivify(childSample, vivify);
+                const proxy = Array.isArray(childSample)
+                    ? toArrayStore(computation, injector, childVivify)
+                    : toStore(computation, injector, childVivify);
                 const ref = new WeakRef(proxy);
                 storeCache.set(idx, ref);
                 PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
@@ -2243,7 +2593,7 @@ function toArrayStore(source, injector) {
  * const state = store({ user: { name: 'John' } });
  * const nameSignal = state.user.name; // WritableSignal<string>
  */
-function toStore(source, injector) {
+function toStore(source, injector, vivify = false) {
     if (isStore(source))
         return source;
     if (!injector)
@@ -2253,7 +2603,8 @@ function toStore(source, injector) {
         : toWritable(source, () => {
             // noop
         });
-    const isMutableSource = isMutable(writableSource);
+    const isWritableSource = isWritableSignal(source);
+    const isMutableSource = isWritableSource && isMutable(writableSource);
     const s = new Proxy(writableSource, {
         has(_, prop) {
             return Reflect.has(untracked(source), prop);
@@ -2281,10 +2632,16 @@ function toStore(source, injector) {
                 return true;
             if (prop === 'asReadonlyStore')
                 return () => {
-                    if (!isWritableSignal(source))
+                    if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), injector));
+                    return untracked(() => toStore(source.asReadonly(), injector, vivify));
                 };
+            if (prop === 'extend')
+                return (seed) => scopedStore(s, seed, isMutableSource
+                    ? 'mutable'
+                    : isWritableSource
+                        ? 'writable'
+                        : 'readonly', injector);
             if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
                 return target[prop];
             let storeCache = PROXY_CACHE.get(target);
@@ -2303,31 +2660,36 @@ function toStore(source, injector) {
             const value = untracked(target);
             const valueIsRecord = isRecord(value);
             const valueIsArray = Array.isArray(value);
+            const nodeVivify = resolveVivify(value, vivify);
+            const vivifyFn = createVivify(nodeVivify);
             const equalFn = (valueIsRecord || valueIsArray) &&
                 isMutableSource &&
                 typeof value[prop] === 'object'
                 ? () => false
                 : undefined;
             const computation = valueIsRecord
-                ? derived(target, prop, { equal: equalFn })
+                ? derived(target, prop, { equal: equalFn, vivify: nodeVivify })
                 : derived(target, {
                     from: (v) => v?.[prop],
                     onChange: (newValue) => target.update((v) => {
-                        if (v === null || v === undefined)
-                            return v;
+                        const container = vivifyFn(v, prop);
+                        if (container === null || container === undefined)
+                            return container;
                         try {
-                            v[prop] = newValue;
+                            container[prop] = newValue;
                         }
                         catch (e) {
                             if (isDevMode())
                                 console.error(`[store] Failed to set property "${String(prop)}"`, e);
                         }
-                        return v;
+                        return container;
                     }),
                 });
-            const proxy = Array.isArray(untracked(computation))
-                ? toArrayStore(computation, injector)
-                : toStore(computation, injector);
+            const childSample = untracked(computation);
+            const childVivify = resolveVivify(childSample, vivify);
+            const proxy = Array.isArray(childSample)
+                ? toArrayStore(computation, injector, childVivify)
+                : toStore(computation, injector, childVivify);
             const ref = new WeakRef(proxy);
             storeCache.set(prop, ref);
             PROXY_CLEANUP.register(proxy, { target, prop }, ref);
@@ -2336,19 +2698,103 @@ function toStore(source, injector) {
     });
     return s;
 }
+/**
+ * @internal
+ * Backs `store.extend(...)`. Builds a scoped overlay over `parent`: the local layer (the seed
+ * plus any keys created later) is its own signal and `parent` is its own signal, so the getter
+ * routes each key by consulting BOTH — local first, then parent, else local (so a write to an
+ * as-yet-unknown key lands locally). Inherited keys return the parent's own sub-store (shared
+ * identity + two-way), while local keys never propagate upward. A merged `computed` is derived
+ * only for whole-object reads / `has` / iteration — never for routing.
+ */
+function scopedStore(parent, seed, kind, injector) {
+    const local = isSignal(seed)
+        ? toStore(seed, injector)
+        : kind === 'mutable'
+            ? mutableStore(seed, { injector })
+            : kind === 'readonly'
+                ? store(seed, { injector }).asReadonlyStore()
+                : store(seed, { injector });
+    const localValue = () => untracked(local);
+    const parentValue = () => untracked(parent);
+    const view = computed(() => ({
+        ...parent(),
+        ...local(),
+    }));
+    const splitSet = (next) => {
+        const lv = localValue();
+        const pv = parentValue();
+        for (const key of Reflect.ownKeys(next)) {
+            const layer = hasOwnKey(lv, key)
+                ? local
+                : hasOwnKey(pv, key)
+                    ? parent
+                    : local;
+            layer[key].set(next[key]);
+        }
+    };
+    const base = toWritable(view, kind === 'readonly' ? () => undefined : splitSet, undefined, { pure: false });
+    if (kind === 'mutable') {
+        base.mutate = (updater) => splitSet(updater(untracked(view)));
+        base.inline = (updater) => base.mutate((prev) => {
+            updater(prev);
+            return prev;
+        });
+    }
+    const scope = new Proxy(base, {
+        get(target, prop) {
+            if (prop === IS_STORE)
+                return true;
+            if (prop === SCOPE_PARENT)
+                return parent;
+            if (prop === 'extend')
+                return (childSeed) => scopedStore(scope, childSeed, kind, injector);
+            if (prop === 'asReadonlyStore')
+                return () => toStore(computed(() => ({ ...parent(), ...local() })), injector);
+            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
+                return target[prop];
+            // Route by consulting both signals: local first, then parent, else local (new → local).
+            if (hasOwnKey(localValue(), prop))
+                return local[prop];
+            if (hasOwnKey(parentValue(), prop))
+                return parent[prop];
+            return local[prop];
+        },
+        has(_, prop) {
+            return hasOwnKey(localValue(), prop) || hasOwnKey(parentValue(), prop);
+        },
+        ownKeys() {
+            return [
+                ...new Set([
+                    ...Reflect.ownKeys(parentValue()),
+                    ...Reflect.ownKeys(localValue()),
+                ]),
+            ];
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            if (hasOwnKey(localValue(), prop) || hasOwnKey(parentValue(), prop))
+                return { enumerable: true, configurable: true };
+            return undefined;
+        },
+        getPrototypeOf() {
+            return Object.prototype;
+        },
+    });
+    return scope;
+}
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
  */
 function store(value, opt) {
-    return toStore(signal(value, opt), opt?.injector);
+    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false);
 }
 /**
  * Creates a MutableSignalStore from a value.
  * @see {@link toStore}
  */
 function mutableStore(value, opt) {
-    return toStore(mutable(value, opt), opt?.injector);
+    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false);
 }
 
 // Internal dummy store for server-side rendering