@mmstack/primitives 20.7.0 → 20.7.2

package/fesm2022/mmstack-primitives.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, InjectionToken, TemplateRef, ViewContainerRef, input, computed, Directive, signal, PLATFORM_ID, runInInjectionContext, afterNextRender, Component, isSignal, ElementRef, Injectable } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, InjectionToken, TemplateRef, ViewContainerRef, PLATFORM_ID, input, computed, Directive, signal, runInInjectionContext, linkedSignal, afterNextRender, Component, isSignal, ElementRef, Injectable } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -155,74 +155,6 @@ function nestedEffect(effectFn, options) {
     return ref;
 }
 
-/**
- * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
- *
- * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `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.
- * @param options Configuration options for chunk size, delay duration, equality function, and injector.
- * @returns A `Signal` that emits the current chunk of items being processed.
- *
- * @example
- * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
- * const chunkedList = chunked(largeList, { chunkSize: 100, delay: 100 });
- */
-function chunked(source, options) {
-    const { chunkSize = 50, delay = 'frame', equal, injector } = options || {};
-    let delayFn;
-    if (delay === 'frame') {
-        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) => {
-            let isCancelled = false;
-            queueMicrotask(() => {
-                if (isCancelled)
-                    return;
-                cb();
-            });
-            return () => {
-                isCancelled = true;
-            };
-        };
-    }
-    else {
-        delayFn = (cb) => {
-            const num = setTimeout(cb, delay);
-            return () => clearTimeout(num);
-        };
-    }
-    const internal = linkedSignal(...(ngDevMode ? [{ debugName: "internal", source,
-            computation: (items) => items.slice(0, chunkSize),
-            equal }] : [{
-            source,
-            computation: (items) => items.slice(0, chunkSize),
-            equal,
-        }]));
-    nestedEffect((cleanup) => {
-        const fullList = source();
-        const current = internal();
-        if (current.length >= fullList.length)
-            return;
-        return cleanup(delayFn(() => untracked(() => internal.set(fullList.slice(0, current.length + chunkSize)))));
-    }, {
-        injector: injector,
-    });
-    return internal.asReadonly();
-}
-
 /**
  * Whether the subtree a resource/component lives in is currently PAUSED, for Activity / keep-alive.
  * Provided by an Activity boundary (`MmActivity`, or the app-builder's per-branch injector) and read
@@ -250,6 +182,7 @@ class MmActivity {
     tpl = inject(TemplateRef);
     vcr = inject(ViewContainerRef);
     parent = inject(Injector);
+    onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     /** When false, keep the content mounted but hidden + CD-detached. */
     visible = input.required(...(ngDevMode ? [{ debugName: "visible", alias: 'mmActivity' }] : [{ alias: 'mmActivity' }]));
     /** Paused == not visible — handed to the kept subtree as PAUSED_CONTEXT. */
@@ -272,6 +205,8 @@ class MmActivity {
                 }),
             });
         }
+        if (this.onServer)
+            return;
         for (const node of this.view.rootNodes) {
             // 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
@@ -316,24 +251,23 @@ function providePaused(source) {
 }
 
 /**
- * Structural hold-and-swap as a signal. Given a `target` (the desired value — e.g. the
- * subtree/def/key you want to show) and a `ready` predicate, returns a signal that keeps
- * yielding its PREVIOUS value until `ready()` is true, then swaps to the current target.
- *
- * This is the structural counterpart to `keepPrevious`/`commit`: where those hold a *value*
- * through a reload, this holds a *structure* through a swap. The caller mounts the incoming
- * structure off to the side (so its resources can settle and flip `ready`), keeps showing the
- * held previous structure meanwhile, and lets the old one go once `ready` releases the swap.
+ * @internal Token carrying an app-wide default {@link PauseOption}, set via
+ * {@link providePausableOptions}. {@link resolvePause} consults it when the call site didn't
+ * specify `pause`, so users can opt every pausable-aware primitive in (or out) from one place.
+ */
+const PAUSABLE_OPTIONS = new InjectionToken('@mmstack/primitives:pausable-options');
+/**
+ * Provides an app-wide default {@link PauseOption} for every pausable-aware primitive (the public
+ * `pausable*` family plus the opt-in integrations like `stored` / `chunked`). A call-site `pause`
+ * always wins; this only fills in when the call didn't specify one.
  *
- * The very first value passes straight through (nothing to hold yet).
+ * @example
+ * // Make everything that can pause honour the ambient Activity boundary by default:
+ * providePausableOptions({ pause: true })
  */
-function holdUntilReady(target, ready) {
-    return linkedSignal({
-        source: () => ({ t: target(), ready: ready() }),
-        computation: (curr, prev) => (prev === undefined || curr.ready ? curr.t : prev.value),
-    });
+function providePausableOptions(opt) {
+    return { provide: PAUSABLE_OPTIONS, useValue: opt };
 }
-
 /**
  * Resolve a {@link PauseOption} into a pause predicate, or `null` meaning "do not pause".
  * `null` tells the caller to return the bare primitive — no wrapper is created.
@@ -348,11 +282,7 @@ function holdUntilReady(target, ready) {
  *
  * Encapsulating this here keeps every pausable primitive's branching identical and in one place.
  */
-function resolvePause(opt) {
-    const explicit = opt?.pause; // distinguish explicit `true` from the omitted default
-    const pause = explicit ?? true; // explicit pausable* calls default to pausing
-    if (pause === false)
-        return null;
+function resolvePause(opt, defaultPause = true) {
     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
@@ -365,6 +295,12 @@ function resolvePause(opt) {
             return fallback;
         }
     };
+    // A `providePausableOptions(...)` default fills in when the call site didn't specify `pause`.
+    const providedPause = tryRun(() => inject(PAUSABLE_OPTIONS, { optional: true })?.pause, undefined);
+    const explicit = opt?.pause ?? providedPause;
+    const pause = explicit ?? defaultPause; // public pausable* default `true`; opt-in integrations `false`
+    if (pause === false)
+        return null;
     const onServer = () => typeof pause === 'function' && !opt?.injector
         ? typeof globalThis.window === 'undefined'
         : tryRun(() => isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser'), typeof globalThis.window === 'undefined');
@@ -374,7 +310,7 @@ function resolvePause(opt) {
         return null;
     const paused = tryRun(() => inject(PAUSED_CONTEXT, { optional: true }), null);
     if (!paused) {
-        if (explicit === true && isDevMode())
+        if (opt?.pause === true && isDevMode())
             console.warn('[pausable] `pause: true` but no PAUSED_CONTEXT in scope — not pausing. Provide one via an ' +
                 'Activity boundary (`MmActivity` / `providePaused`), or pass a predicate / `pause: false`.');
         return null;
@@ -450,6 +386,96 @@ function pausableComputed(computation, options) {
     return ls.asReadonly();
 }
 
+/**
+ * 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 `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.
+ * @param options Configuration options for chunk size, delay duration, equality function, and injector.
+ * @returns A `Signal` that emits the current chunk of items being processed.
+ *
+ * @example
+ * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
+ * const chunkedList = chunked(largeList, { chunkSize: 100, delay: 100 });
+ */
+function chunked(source, options) {
+    const { chunkSize = 50, delay = 'frame', equal, injector, pause, } = options || {};
+    let delayFn;
+    if (delay === 'frame') {
+        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) => {
+            let isCancelled = false;
+            queueMicrotask(() => {
+                if (isCancelled)
+                    return;
+                cb();
+            });
+            return () => {
+                isCancelled = true;
+            };
+        };
+    }
+    else {
+        delayFn = (cb) => {
+            const num = setTimeout(cb, delay);
+            return () => clearTimeout(num);
+        };
+    }
+    const internal = linkedSignal(...(ngDevMode ? [{ debugName: "internal", source,
+            computation: (items) => items.slice(0, chunkSize),
+            equal }] : [{
+            source,
+            computation: (items) => items.slice(0, chunkSize),
+            equal,
+        }]));
+    const paused = resolvePause({ injector, pause }, false);
+    nestedEffect((cleanup) => {
+        if (paused?.())
+            return;
+        const fullList = source();
+        const current = internal();
+        if (current.length >= fullList.length)
+            return;
+        return cleanup(delayFn(() => untracked(() => internal.set(fullList.slice(0, current.length + chunkSize)))));
+    }, {
+        injector,
+    });
+    return internal.asReadonly();
+}
+
+/**
+ * Structural hold-and-swap as a signal. Given a `target` (the desired value — e.g. the
+ * subtree/def/key you want to show) and a `ready` predicate, returns a signal that keeps
+ * yielding its PREVIOUS value until `ready()` is true, then swaps to the current target.
+ *
+ * This is the structural counterpart to `keepPrevious`/`commit`: where those hold a *value*
+ * through a reload, this holds a *structure* through a swap. The caller mounts the incoming
+ * structure off to the side (so its resources can settle and flip `ready`), keeps showing the
+ * held previous structure meanwhile, and lets the old one go once `ready` releases the swap.
+ *
+ * The very first value passes straight through (nothing to hold yet).
+ */
+function holdUntilReady(target, ready) {
+    return linkedSignal({
+        source: () => ({ t: target(), ready: ready() }),
+        computation: (curr, prev) => (prev === undefined || curr.ready ? curr.t : prev.value),
+    });
+}
+
 const { is } = Object;
 function mutable(initial, opt) {
     const baseEqual = opt?.equal ?? is;
@@ -651,6 +677,7 @@ function registerResource(res, opt) {
 function injectStartTransition() {
     const scope = injectTransitionScope();
     const injector = inject(Injector);
+    const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
         untracked(fn);
         let sawPending = false;
@@ -665,6 +692,13 @@ function injectStartTransition() {
                     resolve();
                 }
             }, ...(ngDevMode ? [{ debugName: "watcher", injector }] : [{ injector }]));
+            if (onServer) {
+                if (!untracked(scope.pending)) {
+                    watcher.destroy();
+                    resolve();
+                }
+                return;
+            }
             // no-async fallback: once the reactive system has processed the writes (afterNextRender),
             // if nothing ever went in flight, the transition is already complete.
             afterNextRender(() => {
@@ -692,6 +726,12 @@ function injectStartTransition() {
  *
  * `type` selects what "not ready" means: `'value'` (default) suspends only until a first value lands
  * then holds through reloads; `'loading'` suspends on every in-flight load (strict suspense).
+ *
+ * SSR: the server serializes whatever the scope reports at stabilization, so a registered resource
+ * must keep the app unstable until it settles or the placeholder is what gets serialized (then
+ * flashes/mismatches on hydration). HttpClient-backed resources, httpResource & all of `@mmstack/resource`
+ * do this automatically via the HTTP layer's `PendingTasks` + transfer cache. A custom loader (raw
+ * `fetch`/promise/timer) must opt in itself: wrap it with `inject(PendingTasks).run(() => promise)`.
  */
 class SuspenseBoundaryBase {
     scope = injectTransitionScope();
@@ -805,6 +845,7 @@ function runInTransaction(txn, fn) {
 function injectStartTransaction() {
     const scope = injectTransitionScope();
     const injector = inject(Injector);
+    const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
         const txn = createTransaction();
         // Hold BEFORE the writes, so the display freezes at pre-transaction values.
@@ -846,11 +887,17 @@ function injectStartTransaction() {
             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))
+        if (onServer) {
+            if (!untracked(scope.pending))
                 finish(false);
-        }, { injector });
+        }
+        else {
+            // 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,
@@ -2624,11 +2671,19 @@ function throttle(source, opt) {
         tick();
     };
     const update = (fn) => set(fn(untracked(source)));
+    const flush = () => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = undefined;
+        pendingTrailing = false;
+        fire();
+    };
     const writable = toWritable(computed(() => {
         trigger();
         return untracked(source);
     }, opt), set, update);
     writable.original = source.asReadonly();
+    writable.flush = flush;
     return writable;
 }
 
@@ -2852,77 +2907,265 @@ function createOrientation(debugName) {
     return state.asReadonly();
 }
 
+const IDLE = {
+    active: false,
+    start: { x: 0, y: 0 },
+    current: { x: 0, y: 0 },
+    delta: { x: 0, y: 0 },
+    pointerId: null,
+    modifiers: { shift: false, alt: false, ctrl: false, meta: false },
+    button: -1,
+};
+function stateEqual(a, b) {
+    return (a.active === b.active &&
+        a.pointerId === b.pointerId &&
+        a.current.x === b.current.x &&
+        a.current.y === b.current.y &&
+        a.button === b.button &&
+        a.modifiers.shift === b.modifiers.shift &&
+        a.modifiers.alt === b.modifiers.alt &&
+        a.modifiers.ctrl === b.modifiers.ctrl &&
+        a.modifiers.meta === b.modifiers.meta);
+}
 /**
- * Creates a read-only signal that tracks the page's visibility state.
- *
- * It uses the browser's Page Visibility API to reactively report if the
- * current document is `'visible'`, `'hidden'`, or in another state.
- * The primitive is SSR-safe and automatically cleans up its event listeners
- * when the creating context is destroyed.
- *
- * @param 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'`.
+ * Tracks a pointer *gesture* (pointerdown → capture → move → up) as a signal —
+ * the foundation for pointer-based drag/move/resize/marquee on a canvas. Unlike
+ * native HTML5 drag, pointer events fire continuously and coordinates are
+ * reliable. SSR-safe; cleans up its listeners automatically.
  *
  * @example
  * ```ts
- * import { Component, effect } from '@angular/core';
- * import { pageVisibility } from '@mmstack/primitives';
- *
- * @Component({
- * selector: 'app-visibility-tracker',
- * template: `<p>Page is currently: {{ visibilityState() }}</p>`
- * })
- * export class VisibilityTrackerComponent {
- * readonly visibilityState = pageVisibility();
- *
- * constructor() {
- * effect(() => {
- * if (this.visibilityState() === 'hidden') {
- * console.log('Page is hidden, pausing expensive animations...');
- * } else {
- * console.log('Page is visible, resuming activity.');
- * }
+ * const drag = pointerDrag({ activationThreshold: 4 });
+ * const position = computed(() => {
+ *   const d = drag();
+ *   return d.active ? { x: base.x + d.delta.x, y: base.y + d.delta.y } : base;
  * });
- * }
- * }
  * ```
  */
-function pageVisibility(opt) {
-    const { debugName = 'pageVisibility', injector } = coerceSensorOptions(opt);
-    return runInSensorContext(injector, () => createPageVisibility(debugName));
+function pointerDrag(opt) {
+    return runInSensorContext(opt?.injector, () => createPointerDrag(opt));
 }
-function createPageVisibility(debugName) {
+function createPointerDrag(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
-        return computed(() => 'visible', { debugName });
+        const base = computed(() => IDLE, {
+            debugName: opt?.debugName ?? 'pointerDrag',
+        });
+        base.unthrottled = base;
+        base.cancel = () => undefined;
+        return base;
     }
-    const visibility = signal(document.visibilityState, ...(ngDevMode ? [{ debugName: "visibility", debugName }] : [{ debugName }]));
-    const onVisibilityChange = () => visibility.set(document.visibilityState);
-    document.addEventListener('visibilitychange', onVisibilityChange);
-    inject(DestroyRef).onDestroy(() => document.removeEventListener('visibilitychange', onVisibilityChange));
-    return visibility.asReadonly();
-}
-
-/**
- * Creates a read-only signal that tracks the scroll position (x, y) of the window
- * or a specified HTML element.
- *
- * Updates are throttled by default to optimize performance. An `unthrottled`
- * property is available on the returned signal for direct access to raw updates.
- * The primitive is SSR-safe and automatically cleans up its event listeners.
- *
- * @param options Optional configuration for the scroll sensor.
- * @returns A `ScrollPositionSignal`. On the server, it returns a static
- * signal with `{ x: 0, y: 0 }`.
- *
- * @example
- * ```ts
- * import { Component, effect, ElementRef, viewChild } from '@angular/core';
- * import { scrollPosition } from '@mmstack/primitives';
- *
- * @Component({
- * selector: 'app-scroll-tracker',
+    const hostRef = inject((ElementRef), { optional: true });
+    const { target = hostRef?.nativeElement, coordinateSpace = 'client', activationThreshold = 3, throttle = 16, handleSelector, buttons = [0], debugName = 'pointerDrag', } = opt ?? {};
+    const resolve = (t) => {
+        if (!t)
+            return null;
+        return t instanceof ElementRef ? t.nativeElement : t;
+    };
+    if (!isSignal(target) && !resolve(target)) {
+        if (isDevMode())
+            console.warn('pointerDrag: no target element (host ElementRef missing).');
+        const base = computed(() => IDLE, { debugName });
+        base.unthrottled = base;
+        base.cancel = () => undefined;
+        return base;
+    }
+    const state = throttled(IDLE, {
+        ms: throttle,
+        leading: true,
+        trailing: true,
+        equal: stateEqual,
+        debugName,
+    });
+    let startPoint = { x: 0, y: 0 };
+    let activePointerId = null;
+    let activeButton = -1;
+    let activated = false;
+    let gesture = null;
+    const coord = (e) => coordinateSpace === 'page'
+        ? { x: e.pageX, y: e.pageY }
+        : { x: e.clientX, y: e.clientY };
+    const mods = (e) => ({
+        shift: e.shiftKey,
+        alt: e.altKey,
+        ctrl: e.ctrlKey,
+        meta: e.metaKey,
+    });
+    const end = () => {
+        gesture?.abort();
+        gesture = null;
+        activePointerId = null;
+        activeButton = -1;
+        activated = false;
+        state.set(IDLE);
+        state.flush(); // terminal transition: reflect IDLE now, not on the trailing edge
+    };
+    const onMove = (e) => {
+        if (e.pointerId !== activePointerId)
+            return;
+        const current = coord(e);
+        const delta = { x: current.x - startPoint.x, y: current.y - startPoint.y };
+        if (!activated && Math.hypot(delta.x, delta.y) >= activationThreshold) {
+            activated = true;
+        }
+        state.set({
+            active: activated,
+            start: startPoint,
+            current,
+            delta,
+            pointerId: activePointerId,
+            modifiers: mods(e),
+            button: activeButton, // pointermove button is -1; keep the down-button
+        });
+    };
+    const onUp = (e) => {
+        if (e.pointerId === activePointerId)
+            end();
+    };
+    const onCancel = (e) => {
+        if (e.pointerId === activePointerId)
+            end();
+    };
+    const onKey = (e) => {
+        if (e.key === 'Escape' && activePointerId !== null)
+            end();
+    };
+    const onDown = (el) => (e) => {
+        if (activePointerId !== null)
+            return;
+        if (!buttons.includes(e.button))
+            return;
+        if (handleSelector && !e.target?.closest?.(handleSelector)) {
+            return;
+        }
+        activePointerId = e.pointerId;
+        activeButton = e.button;
+        activated = false;
+        startPoint = coord(e);
+        try {
+            el.setPointerCapture(e.pointerId);
+        }
+        catch {
+            // capture unsupported (older browsers / test env) — listeners still work
+        }
+        gesture = new AbortController();
+        const signal = gesture.signal;
+        el.addEventListener('pointermove', onMove, { signal });
+        el.addEventListener('pointerup', onUp, { signal });
+        el.addEventListener('pointercancel', onCancel, { signal });
+        el.addEventListener('lostpointercapture', onCancel, {
+            signal,
+        });
+        window.addEventListener('keydown', onKey, { signal });
+        state.set({
+            active: false,
+            start: startPoint,
+            current: startPoint,
+            delta: { x: 0, y: 0 },
+            pointerId: e.pointerId,
+            modifiers: mods(e),
+            button: e.button,
+        });
+    };
+    const attach = (el) => {
+        const controller = new AbortController();
+        el.addEventListener('pointerdown', onDown(el), {
+            signal: controller.signal,
+        });
+        return () => {
+            controller.abort();
+            end();
+        };
+    };
+    if (isSignal(target)) {
+        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 = state.asReadonly();
+    base.unthrottled = state.original;
+    base.cancel = end;
+    return base;
+}
+
+/**
+ * Creates a read-only signal that tracks the page's visibility state.
+ *
+ * It uses the browser's Page Visibility API to reactively report if the
+ * current document is `'visible'`, `'hidden'`, or in another state.
+ * The primitive is SSR-safe and automatically cleans up its event listeners
+ * when the creating context is destroyed.
+ *
+ * @param 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'`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { pageVisibility } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-visibility-tracker',
+ * template: `<p>Page is currently: {{ visibilityState() }}</p>`
+ * })
+ * export class VisibilityTrackerComponent {
+ * readonly visibilityState = pageVisibility();
+ *
+ * constructor() {
+ * effect(() => {
+ * if (this.visibilityState() === 'hidden') {
+ * console.log('Page is hidden, pausing expensive animations...');
+ * } else {
+ * console.log('Page is visible, resuming activity.');
+ * }
+ * });
+ * }
+ * }
+ * ```
+ */
+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 });
+    }
+    const visibility = signal(document.visibilityState, ...(ngDevMode ? [{ debugName: "visibility", debugName }] : [{ debugName }]));
+    const onVisibilityChange = () => visibility.set(document.visibilityState);
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    inject(DestroyRef).onDestroy(() => document.removeEventListener('visibilitychange', onVisibilityChange));
+    return visibility.asReadonly();
+}
+
+/**
+ * Creates a read-only signal that tracks the scroll position (x, y) of the window
+ * or a specified HTML element.
+ *
+ * Updates are throttled by default to optimize performance. An `unthrottled`
+ * property is available on the returned signal for direct access to raw updates.
+ * The primitive is SSR-safe and automatically cleans up its event listeners.
+ *
+ * @param options Optional configuration for the scroll sensor.
+ * @returns A `ScrollPositionSignal`. On the server, it returns a static
+ * signal with `{ x: 0, y: 0 }`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, ElementRef, viewChild } from '@angular/core';
+ * import { scrollPosition } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-scroll-tracker',
  * template: `
  * <p>Window Scroll: X: {{ windowScroll().x }}, Y: {{ windowScroll().y }}</p>
  * <p>Host Scroll: X: {{ hostScroll().x }}, Y: {{ hostScroll().y }}</p>
@@ -3078,6 +3321,8 @@ function sensor(type, options) {
     switch (type) {
         case 'mousePosition':
             return mousePosition(opts);
+        case 'pointerDrag':
+            return pointerDrag(opts);
         case 'networkStatus':
             return networkStatus(opts);
         case 'pageVisibility':
@@ -3195,6 +3440,52 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
     return untracked(() => state.asReadonly());
 }
 
+const IS_STORE = Symbol('@mmstack/primitives::store/IS_STORE');
+const SCOPE_PARENT = Symbol('@mmstack/primitives::store/SCOPE_PARENT');
+/**
+ * @internal Brand carrying a store's writability ('mutable' | 'writable' | 'readonly'), stamped
+ * on every store proxy. Read by `extendStore` instead of re-deriving via `isWritableSignal`,
+ * which would mis-classify a readonly scoped store (its backing `toWritable` still has a `set`).
+ */
+const STORE_KIND = Symbol('@mmstack/primitives::store/STORE_KIND');
+/**
+ * @internal Brand exposing the injector a store was built with, so `extendStore` inherits it the
+ * same way `store.extend(...)` does (via closure) — no injection context needed at the call site.
+ */
+const STORE_INJECTOR = Symbol('@mmstack/primitives::store/STORE_INJECTOR');
+const SIGNAL_FN_PROP = new Set([
+    'set',
+    'update',
+    'mutate',
+    'inline',
+    'asReadonly',
+]);
+/**
+ * @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();
+/**
+ * @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)
+        storeCache.delete(prop);
+});
+/**
+ * @internal
+ * Validates whether a value is a Signal Store.
+ */
+function isStore(value) {
+    return (typeof value === 'function' &&
+        value !== null &&
+        value[IS_STORE] === true);
+}
+
 /**
  * Runtime marker + compile-time brand for an opaque value. A `const`-declared `Symbol`
  * has a `unique symbol` type, so the same symbol serves as both the property key written
@@ -3236,12 +3527,13 @@ function isOpaque(value) {
         value !== null &&
         value[OPAQUE] === true);
 }
-/**
- * @internal Runtime brand carrying a store node's lazily-built leaf probe. Exported (like
- * {@link OPAQUE}) only so the `{ readonly [LEAF]: () => boolean }` brand on the store types is
- * nameable in the emitted declarations — not part of the supported surface; use {@link isLeaf}.
- */
-const LEAF = Symbol('@mmstack/primitives::store/LEAF');
+
+function isRecord(value) {
+    if (value === null || typeof value !== 'object' || isOpaque(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 /**
  * @internal Whether a value is a terminal leaf: a concrete non-record/non-array value always is;
  * `null`/`undefined` is a leaf only when vivification is disabled (with vivify on it can still
@@ -3254,6 +3546,65 @@ function isLeafValue(value, vivifyEnabled) {
         return true; // opaque always wins — even arrays
     return !Array.isArray(value) && !isRecord(value);
 }
+/**
+ * @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
+ * 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 Runtime brand carrying a store node's lazily-built leaf probe. Exported (like
+ * {@link OPAQUE}) only so the `{ readonly [LEAF]: () => boolean }` brand on the store types is
+ * nameable in the emitted declarations — not part of the supported surface; use {@link isLeaf}.
+ */
+const LEAF = Symbol('@mmstack/primitives::store/LEAF');
 /**
  * @internal Constant leaf probes for nodes whose leaf-ness is statically known, so the reactive
  * `computed` can be skipped entirely.
@@ -3311,227 +3662,72 @@ function markAsLeaf(sig, value, vivifyEnabled, noUnionLeaves) {
 function isLeaf(value) {
     return isStore(value) && value[LEAF]?.() === true;
 }
-const IS_STORE = Symbol('@mmstack/primitives::store/IS_STORE');
-const SCOPE_PARENT = Symbol('@mmstack/primitives::store/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',
-    'update',
-    'mutate',
-    '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.
+ * @internal Reads (or lazily builds + caches) the child node proxy for `prop` on `target`,
+ * holding it via a `WeakRef` and registering it for finalizer-driven cache pruning. The cache
+ * is keyed per backing signal, so child identity is stable across repeat reads.
  */
-const PROXY_CLEANUP = new FinalizationRegistry(({ target, prop }) => {
-    const storeCache = PROXY_CACHE.get(target);
-    if (storeCache)
+function getCachedChild(target, prop, build) {
+    let storeCache = PROXY_CACHE.get(target);
+    if (!storeCache) {
+        storeCache = new Map();
+        PROXY_CACHE.set(target, storeCache);
+    }
+    const cachedRef = storeCache.get(prop);
+    if (cachedRef) {
+        const cached = cachedRef.deref();
+        if (cached)
+            return cached;
         storeCache.delete(prop);
-});
-/**
- * @internal
- * Validates whether a value is a Signal Store.
- */
-function isStore(value) {
-    return (typeof value === 'function' &&
-        value !== null &&
-        value[IS_STORE] === true);
-}
-function isRecord(value) {
-    if (value === null || typeof value !== 'object' || isOpaque(value))
-        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
- * 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));
+        PROXY_CLEANUP.unregister(cachedRef);
+    }
+    const proxy = build();
+    const ref = new WeakRef(proxy);
+    storeCache.set(prop, ref);
+    PROXY_CLEANUP.register(proxy, { target, prop }, ref);
+    return proxy;
 }
 /**
- * @internal
- * Makes an array store
+ * @internal Builds the derived child signal for `prop` and wraps it as an array/object substore.
+ * A record parent reads the key directly; any other container goes through the fallback `from`/
+ * `onChange` path. Shared verbatim by the array and object proxies — the only place a child node
+ * is constructed.
  */
-function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
-    if (isStore(source))
-        return source;
-    const isMutableSource = isMutable(source);
-    const lengthSignal = computed(() => {
-        const v = source();
-        if (!Array.isArray(v))
-            return 0;
-        return v.length;
-    }, ...(ngDevMode ? [{ debugName: "lengthSignal" }] : []));
-    return new Proxy(source, {
-        has(_, prop) {
-            if (prop === 'length')
-                return true;
-            if (isIndexProp(prop)) {
-                const idx = +prop;
-                return idx >= 0 && idx < untracked(lengthSignal);
-            }
-            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);
-            if (!Array.isArray(v))
-                return [];
-            const len = v.length;
-            const arr = new Array(len + 1);
-            for (let i = 0; i < len; i++) {
-                arr[i] = String(i);
-            }
-            arr[len] = 'length';
-            return arr;
-        },
-        getPrototypeOf() {
-            return Array.prototype;
-        },
-        getOwnPropertyDescriptor(_, prop) {
-            const v = untracked(source);
-            if (!Array.isArray(v))
-                return;
-            if (prop === 'length' ||
-                (typeof prop === 'string' && !isNaN(+prop) && +prop < v.length)) {
-                return {
-                    enumerable: true,
-                    configurable: true, // Required for proxies to dynamic targets
-                };
-            }
-            return;
-        },
-        get(target, prop, receiver) {
-            if (prop === IS_STORE)
-                return true;
-            if (prop === 'length')
-                return lengthSignal;
-            if (prop === Symbol.iterator) {
-                return function* () {
-                    // 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];
-                    }
-                };
-            }
-            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
-                return target[prop];
-            if (isIndexProp(prop)) {
-                const idx = +prop;
-                let storeCache = PROXY_CACHE.get(target);
-                if (!storeCache) {
-                    storeCache = new Map();
-                    PROXY_CACHE.set(target, storeCache);
-                }
-                const cachedRef = storeCache.get(idx);
-                if (cachedRef) {
-                    const cached = cachedRef.deref();
-                    if (cached)
-                        return cached;
-                    storeCache.delete(idx);
-                    PROXY_CLEANUP.unregister(cachedRef);
-                }
-                const value = untracked(target);
-                const valueIsArray = Array.isArray(value);
-                const valueIsRecord = isRecord(value);
-                const 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,
-                        vivify: nodeVivify,
-                    })
-                    : derived(target, {
-                        from: (v) => v?.[idx],
-                        onChange: createFallbackOnChange(target, idx, vivifyFn, isMutableSource),
-                        equal: equalFn,
-                    });
-                const childSample = untracked(computation);
-                const childVivify = resolveVivify(childSample, vivify);
-                const proxy = Array.isArray(childSample) && !isOpaque(childSample)
-                    ? toArrayStore(computation, injector, childVivify, noUnionLeaves)
-                    : toStore(computation, injector, childVivify, noUnionLeaves);
-                markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
-                const ref = new WeakRef(proxy);
-                storeCache.set(idx, ref);
-                PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
-                return proxy;
-            }
-            return Reflect.get(target, prop, receiver);
-        },
-    });
+function buildChildNode(target, prop, isMutableSource, injector, vivify, noUnionLeaves) {
+    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, vivify: nodeVivify })
+        : derived(target, {
+            from: (v) => v?.[prop],
+            onChange: createFallbackOnChange(target, prop, vivifyFn, isMutableSource),
+            equal: equalFn,
+        });
+    const childSample = untracked(computation);
+    const childVivify = resolveVivify(childSample, vivify);
+    const proxy = toStore(computation, injector, childVivify, noUnionLeaves);
+    markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
+    return proxy;
 }
 /**
  * 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.
+ * A node's *container kind* (array / record / primitive) is tracked reactively via a per-node
+ * `kind` computed, so the same proxy serves all three and a union node that flips between an
+ * array and a record keeps working. Flips are route-forward: after a flip the node behaves as
+ * its new kind on the next access, while child proxies cached under the old shape go stale and
+ * are pruned by the GC.
  *
  * @example
  * const state = store({ user: { name: 'John' } });
@@ -3549,92 +3745,114 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
         });
     const isWritableSource = isWritableSignal(source);
     const isMutableSource = isWritableSource && isMutable(writableSource);
+    const kind = computed(() => {
+        const v = source();
+        if (Array.isArray(v) && !isOpaque(v))
+            return 'array';
+        if (isRecord(v))
+            return 'record';
+        return 'primitive';
+    }, ...(ngDevMode ? [{ debugName: "kind" }] : []));
+    // built lazily so non-array nodes never allocate it
+    let length;
+    const arrayLength = () => (length ??= computed(() => {
+        const v = source();
+        return Array.isArray(v) ? v.length : 0;
+    }));
     const s = new Proxy(writableSource, {
         has(_, prop) {
-            return Reflect.has(untracked(source), prop);
+            const v = untracked(source);
+            if (untracked(kind) === 'array') {
+                if (prop === 'length')
+                    return true;
+                if (isIndexProp(prop)) {
+                    const idx = +prop;
+                    return idx >= 0 && idx < v.length;
+                }
+            }
+            // 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);
+            if (untracked(kind) === 'array') {
+                const len = v.length;
+                const arr = new Array(len + 1);
+                for (let i = 0; i < len; i++)
+                    arr[i] = String(i);
+                arr[len] = 'length';
+                return arr;
+            }
             if (!isRecord(v))
                 return [];
             return Reflect.ownKeys(v);
         },
         getPrototypeOf() {
-            return Object.getPrototypeOf(untracked(source));
+            if (untracked(kind) === 'array')
+                return Array.prototype;
+            const v = untracked(source);
+            return v == null ? Object.prototype : Object.getPrototypeOf(v);
         },
         getOwnPropertyDescriptor(_, prop) {
-            const value = untracked(source);
-            if (!isRecord(value) || !(prop in value))
+            const v = untracked(source);
+            if (untracked(kind) === 'array') {
+                if (prop === 'length' ||
+                    (typeof prop === 'string' && !isNaN(+prop) && +prop < v.length))
+                    return { enumerable: true, configurable: true };
                 return;
-            return {
-                enumerable: true,
-                configurable: true,
-            };
+            }
+            if (!isRecord(v) || !(prop in v))
+                return;
+            return { enumerable: true, configurable: true };
         },
-        get(target, prop) {
+        get(target, prop, receiver) {
             if (prop === IS_STORE)
                 return true;
+            if (prop === STORE_KIND)
+                return isMutableSource
+                    ? 'mutable'
+                    : isWritableSource
+                        ? 'writable'
+                        : 'readonly';
+            if (prop === STORE_INJECTOR)
+                return injector;
             if (prop === 'asReadonlyStore')
                 return () => {
                     if (!isWritableSource)
                         return s;
                     return untracked(() => toStore(source.asReadonly(), injector, vivify, noUnionLeaves));
                 };
-            if (prop === 'extend')
+            const k = untracked(kind);
+            if (prop === 'extend' && k !== 'array')
                 return (seed) => scopedStore(s, seed, isMutableSource
                     ? 'mutable'
                     : isWritableSource
                         ? 'writable'
                         : 'readonly', injector);
+            if (k === 'array') {
+                if (prop === 'length')
+                    return arrayLength();
+                if (prop === Symbol.iterator)
+                    return function* () {
+                        // 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
+                        const len = arrayLength();
+                        for (let i = 0; i < len(); i++)
+                            yield receiver[i];
+                    };
+            }
             if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
                 return target[prop];
-            let storeCache = PROXY_CACHE.get(target);
-            if (!storeCache) {
-                storeCache = new Map();
-                PROXY_CACHE.set(target, storeCache);
-            }
-            const cachedRef = storeCache.get(prop);
-            if (cachedRef) {
-                const cached = cachedRef.deref();
-                if (cached)
-                    return cached;
-                storeCache.delete(prop);
-                PROXY_CLEANUP.unregister(cachedRef);
-            }
-            const value = untracked(target);
-            const valueIsRecord = isRecord(value);
-            const valueIsArray = Array.isArray(value);
-            const 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, vivify: nodeVivify })
-                : derived(target, {
-                    from: (v) => v?.[prop],
-                    onChange: createFallbackOnChange(target, prop, vivifyFn, isMutableSource),
-                    equal: equalFn,
-                });
-            const childSample = untracked(computation);
-            const childVivify = resolveVivify(childSample, vivify);
-            const proxy = Array.isArray(childSample) && !isOpaque(childSample)
-                ? toArrayStore(computation, injector, childVivify, noUnionLeaves)
-                : toStore(computation, injector, childVivify, noUnionLeaves);
-            markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
-            const ref = new WeakRef(proxy);
-            storeCache.set(prop, ref);
-            PROXY_CLEANUP.register(proxy, { target, prop }, ref);
-            return proxy;
+            if (k === 'array' && !isIndexProp(prop))
+                return Reflect.get(target, prop, receiver);
+            return getCachedChild(target, prop, () => buildChildNode(target, k === 'array' ? +prop : prop, isMutableSource, injector, vivify, noUnionLeaves));
         },
     });
     return s;
 }
 /**
  * @internal
- * Backs `store.extend(...)`. Builds a scoped overlay over `parent`: the local layer (the seed
+ * Backs `extendStore(...)`. 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
@@ -3681,6 +3899,10 @@ function scopedStore(parent, seed, kind, injector) {
         get(target, prop) {
             if (prop === IS_STORE)
                 return true;
+            if (prop === STORE_KIND)
+                return kind;
+            if (prop === STORE_INJECTOR)
+                return injector;
             if (prop === SCOPE_PARENT)
                 return parent;
             if (prop === 'extend')
@@ -3713,6 +3935,28 @@ function scopedStore(parent, seed, kind, injector) {
     });
     return scope;
 }
+/** @internal Reads a store's writability brand, falling back to signal inspection if unbranded. */
+function storeKind(s) {
+    return (s[STORE_KIND] ??
+        (isWritableSignal(s) ? (isMutable(s) ? 'mutable' : 'writable') : 'readonly'));
+}
+/**
+ * Extends a store with extra keys via a scoped overlay, returning a new store that reads through
+ * to the parent for inherited keys (shared identity + two-way) while holding the new keys locally.
+ *
+ * The typesafe successor to the deprecated `store.extend(...)` method — moving it off the proxy
+ * frees the `extend` key for use as a normal record key. Writability (readonly/writable/mutable)
+ * is inherited from `store`.
+ *
+ * @example
+ * const base = store({ count: 0 });
+ * const scoped = extendStore(base, { label: 'live' });
+ * scoped.count.set(1); // writes through to base
+ * scoped.label.set('x'); // stays local
+ */
+function extendStore(store, source, injector) {
+    return scopedStore(store, source, storeKind(store), injector ?? store[STORE_INJECTOR] ?? inject(Injector));
+}
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
@@ -3798,6 +4042,26 @@ function forkStore(base, opt) {
     };
 }
 
+/**
+ * @internal The plain-`effect` sibling of the public {@link pausableEffect} (which is built on
+ * `nestedEffect`). For infra utilities that own a single top-level effect/subscription and don't
+ * need frame/nesting semantics. Opt-in (default off): with no `pause` (call site or
+ * `providePausableOptions` default) it returns a bare `effect` (zero overhead, byte-identical to
+ * today); otherwise it gates the body on the resolved predicate — read FIRST so the dependency set
+ * collapses to just the predicate while paused, re-tracking on resume. Deliberately NOT re-exported
+ * from the public barrel.
+ */
+function pausablePureEffect(effectFn, options) {
+    const paused = resolvePause(options, false);
+    if (!paused)
+        return effect(effectFn, options);
+    return effect((registerCleanup) => {
+        if (paused())
+            return;
+        effectFn(registerCleanup);
+    }, options);
+}
+
 // Internal dummy store for server-side rendering
 const noopStore = {
     getItem: () => null,
@@ -3859,8 +4123,9 @@ const noopStore = {
  * }
  * ```
  */
-function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, validate = () => true, ...rest }) {
-    const isServer = isPlatformServer(inject(PLATFORM_ID));
+function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, validate = () => true, pause, injector: providedInjector, ...rest }) {
+    const injector = providedInjector ?? inject(Injector);
+    const isServer = isPlatformServer(injector.get(PLATFORM_ID));
     const fallbackStore = isServer ? noopStore : localStorage;
     const store = providedStore ?? fallbackStore;
     const keySig = typeof key === 'string'
@@ -3868,8 +4133,6 @@ 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);
@@ -3923,7 +4186,7 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         }]));
     let prevKey = initialKey;
     if (onKeyChange === 'store') {
-        effect(() => {
+        pausablePureEffect(() => {
             const k = keySig();
             storeValue(k, internal());
             if (prevKey !== k) {
@@ -3931,10 +4194,10 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
                     store.removeItem(prevKey);
                 prevKey = k;
             }
-        });
+        }, { injector, pause });
     }
     else {
-        effect(() => {
+        pausablePureEffect(() => {
             const k = keySig();
             const internalValue = internal();
             if (k === prevKey) {
@@ -3947,14 +4210,11 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
                 prevKey = k;
                 internal.set(value); // load new value
             }
-        });
+        }, { injector, pause });
     }
     if (syncTabs && !isServer) {
-        const destroyRef = inject(DestroyRef);
+        const destroyRef = injector.get(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))
@@ -4083,29 +4343,26 @@ function generateDeterministicID() {
  *
  */
 function tabSync(sig, opt) {
-    if (isPlatformServer(inject(PLATFORM_ID)))
+    const optObj = typeof opt === 'object' ? opt : undefined;
+    const injector = optObj?.injector ?? inject(Injector);
+    if (isPlatformServer(injector.get(PLATFORM_ID)))
         return sig;
     const id = typeof opt === 'string' ? opt : (opt?.id ?? generateDeterministicID());
-    const bus = inject(MessageBus);
-    // 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 bus = injector.get(MessageBus);
     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;
+    let firstDone = false;
     const effectRef = effect(() => {
         const val = sig();
-        if (!first) {
-            first = true;
+        if (!firstDone) {
+            firstDone = true;
             return;
         }
         if (val === received) {
@@ -4114,8 +4371,8 @@ function tabSync(sig, opt) {
         }
         received = NONE;
         post(val);
-    }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
-    inject(DestroyRef).onDestroy(() => {
+    }, ...(ngDevMode ? [{ debugName: "effectRef", injector }] : [{ injector }]));
+    injector.get(DestroyRef).onDestroy(() => {
         effectRef.destroy();
         unsub();
     });
@@ -4319,5 +4576,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-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 };
+export { MmActivity, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, 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, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, 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