@mmstack/primitives 22.2.1 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "22.2.1",
+  "version": "22.3.0",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -1,7 +1,94 @@
 import * as i0 from '@angular/core';
-import { ValueEqualityFn, Injector, Signal, Provider, CreateComputedOptions, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, CreateSignalOptions, WritableSignal, ResourceRef, DestroyRef, ElementRef } from '@angular/core';
+import { InjectionToken, Injector, CreateComputedOptions, Signal, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, CreateSignalOptions, WritableSignal, Provider, ValueEqualityFn, ResourceRef, DestroyRef, ElementRef } from '@angular/core';
 import * as _mmstack_primitives from '@mmstack/primitives';
 
+/**
+ * How a pausable primitive decides whether it is currently paused:
+ *  - omitted (the default) or `true` — read the ambient {@link PAUSED_CONTEXT} (via `injector`, or the
+ *    current injection context). Reaching for a `pausable*` primitive means you want it pausable, so
+ *    this is the default; outside an Activity boundary there's no `PAUSED_CONTEXT`, so the primitive is
+ *    returned unwrapped (never pauses, zero overhead). On the server it never pauses either.
+ *  - a predicate `() => boolean` — used directly. A `Signal<boolean>` satisfies this (signals are
+ *    callable), and a plain function works OUTSIDE an injection context.
+ *  - `false` — the explicit opt-out: the primitive is returned UNWRAPPED (no `linkedSignal`, no gate),
+ *    i.e. exactly the plain primitive with zero overhead.
+ */
+type PauseOption = boolean | (() => boolean);
+type PausableOptions = {
+    /** Pause source — see {@link PauseOption}. Defaults to `true` (read the ambient `PAUSED_CONTEXT`). */
+    readonly pause?: PauseOption;
+    /**
+     * Injector used to resolve {@link PAUSED_CONTEXT} when `pause` is `true`/omitted and the primitive
+     * is created outside an injection context. Ignored for the `false` / predicate forms.
+     */
+    readonly injector?: Injector;
+};
+/**
+ * @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.
+ */
+declare const PAUSABLE_OPTIONS: InjectionToken<{
+    pause?: PauseOption;
+}>;
+/**
+ * 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.
+ *
+ * @example
+ * // Make everything that can pause honour the ambient Activity boundary by default:
+ * providePausableOptions({ pause: true })
+ */
+declare function providePausableOptions(opt: {
+    /** Default pause source for pausable-aware primitives that don't set their own. */
+    pause?: PauseOption;
+}): Provider;
+/**
+ * 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.
+ *
+ *  - omitted/`true` → the ambient {@link PAUSED_CONTEXT} if an Activity boundary provides one (via
+ *    `opt.injector` or the current injection context), else `null` (the bare primitive, no allocation).
+ *    The default, because an explicit `pausable*` call wants to be pausable. An explicit `pause: true`
+ *    with no boundary dev-warns; the omitted default stays quiet. SSR → `null`.
+ *  - a function → returned as-is (covers `Signal<boolean>`; usable outside an injection context).
+ *    SSR → `null` here too, detected via `opt.injector` if given, else a `globalThis.window` probe.
+ *  - `false` → `null` (the explicit opt-out).
+ *
+ * Encapsulating this here keeps every pausable primitive's branching identical and in one place.
+ */
+declare function resolvePause(opt?: PausableOptions, defaultPause?: PauseOption): (() => boolean) | null;
+/**
+ * Like {@link nestedEffect}, but pausable. While paused the effect does NOT run its body — and,
+ * crucially, it reads the pause predicate FIRST, so while paused its dependency set collapses to just
+ * the predicate (no churn from the real deps); on resume it re-runs and re-tracks. With no `pause`
+ * option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false` makes it a plain `nestedEffect`
+ * with zero added overhead.
+ */
+declare function pausableEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & PausableOptions): EffectRef;
+/**
+ * Like `signal`, but pausable. While paused, READS hold the last value; writes still land on the
+ * underlying signal and surface on resume. Built on the `keepPrevious`/`hold` shape — a
+ * `linkedSignal` gated on the pause predicate, with `set`/`update` forwarded to the source signal.
+ * `asReadonly()` returns the held (gated) view, so both views of the signal agree while paused.
+ * With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
+ * makes it a plain `signal` — no `linkedSignal` is created.
+ *
+ * NOTE: while paused, `set(x)` followed by a read returns the *held* (pre-pause) value, not `x` — the
+ * write lands on the source and surfaces on resume. That is the "freeze the displayed value while
+ * hidden" semantics; do not rely on read-after-write while paused.
+ */
+declare function pausableSignal<T>(initialValue: T, options?: CreateSignalOptions<T> & PausableOptions): WritableSignal<T>;
+/**
+ * Like `computed`, but pausable. While paused it holds its last value AND does not recompute: the
+ * computation's dependencies are not read while paused, so a dependency change can't trigger work —
+ * on resume it recomputes and re-tracks. The very first read always computes, to seed a value. With
+ * no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false` makes it a plain
+ * `computed`.
+ */
+declare function pausableComputed<T>(computation: () => T, options?: CreateComputedOptions<T> & PausableOptions): Signal<T>;
+
 type CreateChunkedOptions<T> = {
     /**
      * The number of items to process in each chunk.
@@ -21,6 +108,12 @@ type CreateChunkedOptions<T> = {
      * An optional `Injector` to use for the internal effect. This allows the effect to have access to dependency injection if needed.
      */
     injector?: Injector;
+    /**
+     * Opt-in pause: gate the chunk-scheduling effect on an ambient Activity boundary (`true`), a
+     * custom predicate, or `false` (default — no pausing). While paused, scheduling stops and resumes
+     * from the current chunk on resume. See {@link PauseOption}.
+     */
+    pause?: PauseOption;
 };
 /**
  * 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.
@@ -95,72 +188,6 @@ declare function providePaused(source: Signal<boolean>): Provider;
  */
 declare function holdUntilReady<T>(target: Signal<T>, ready: () => boolean): Signal<T>;
 
-/**
- * How a pausable primitive decides whether it is currently paused:
- *  - omitted (the default) or `true` — read the ambient {@link PAUSED_CONTEXT} (via `injector`, or the
- *    current injection context). Reaching for a `pausable*` primitive means you want it pausable, so
- *    this is the default; outside an Activity boundary there's no `PAUSED_CONTEXT`, so the primitive is
- *    returned unwrapped (never pauses, zero overhead). On the server it never pauses either.
- *  - a predicate `() => boolean` — used directly. A `Signal<boolean>` satisfies this (signals are
- *    callable), and a plain function works OUTSIDE an injection context.
- *  - `false` — the explicit opt-out: the primitive is returned UNWRAPPED (no `linkedSignal`, no gate),
- *    i.e. exactly the plain primitive with zero overhead.
- */
-type PauseOption = boolean | (() => boolean);
-type PausableOptions = {
-    /** Pause source — see {@link PauseOption}. Defaults to `true` (read the ambient `PAUSED_CONTEXT`). */
-    readonly pause?: PauseOption;
-    /**
-     * Injector used to resolve {@link PAUSED_CONTEXT} when `pause` is `true`/omitted and the primitive
-     * is created outside an injection context. Ignored for the `false` / predicate forms.
-     */
-    readonly injector?: Injector;
-};
-/**
- * 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.
- *
- *  - omitted/`true` → the ambient {@link PAUSED_CONTEXT} if an Activity boundary provides one (via
- *    `opt.injector` or the current injection context), else `null` (the bare primitive, no allocation).
- *    The default, because an explicit `pausable*` call wants to be pausable. An explicit `pause: true`
- *    with no boundary dev-warns; the omitted default stays quiet. SSR → `null`.
- *  - a function → returned as-is (covers `Signal<boolean>`; usable outside an injection context).
- *    SSR → `null` here too, detected via `opt.injector` if given, else a `globalThis.window` probe.
- *  - `false` → `null` (the explicit opt-out).
- *
- * Encapsulating this here keeps every pausable primitive's branching identical and in one place.
- */
-declare function resolvePause(opt?: PausableOptions): (() => boolean) | null;
-/**
- * Like {@link nestedEffect}, but pausable. While paused the effect does NOT run its body — and,
- * crucially, it reads the pause predicate FIRST, so while paused its dependency set collapses to just
- * the predicate (no churn from the real deps); on resume it re-runs and re-tracks. With no `pause`
- * option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false` makes it a plain `nestedEffect`
- * with zero added overhead.
- */
-declare function pausableEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & PausableOptions): EffectRef;
-/**
- * Like `signal`, but pausable. While paused, READS hold the last value; writes still land on the
- * underlying signal and surface on resume. Built on the `keepPrevious`/`hold` shape — a
- * `linkedSignal` gated on the pause predicate, with `set`/`update` forwarded to the source signal.
- * `asReadonly()` returns the held (gated) view, so both views of the signal agree while paused.
- * With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
- * makes it a plain `signal` — no `linkedSignal` is created.
- *
- * NOTE: while paused, `set(x)` followed by a read returns the *held* (pre-pause) value, not `x` — the
- * write lands on the source and surfaces on resume. That is the "freeze the displayed value while
- * hidden" semantics; do not rely on read-after-write while paused.
- */
-declare function pausableSignal<T>(initialValue: T, options?: CreateSignalOptions<T> & PausableOptions): WritableSignal<T>;
-/**
- * Like `computed`, but pausable. While paused it holds its last value AND does not recompute: the
- * computation's dependencies are not read while paused, so a dependency change can't trigger work —
- * on resume it recomputes and re-tracks. The very first read always computes, to seed a value. With
- * no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false` makes it a plain
- * `computed`.
- */
-declare function pausableComputed<T>(computation: () => T, options?: CreateComputedOptions<T> & PausableOptions): Signal<T>;
-
 /**
  * Handle for an in-progress transition: a `pending` signal (true while the transition's
  * resources are in flight) and a `done` promise that resolves once they all settle.
@@ -288,6 +315,12 @@ declare function registerResource<T extends ResourceRef<any>>(res: T, opt?: Regi
  *
  * `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)`.
  */
 declare abstract class SuspenseBoundaryBase {
     protected readonly scope: _mmstack_primitives.TransitionScope;
@@ -1879,6 +1912,93 @@ type ScreenOrientation = ScreenOrientationState;
  */
 declare function orientation(opt?: string | SensorRunOptions): Signal<ScreenOrientationState>;
 
+type PointerPoint = {
+    x: number;
+    y: number;
+};
+type PointerModifiers = {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+};
+type PointerDragState = {
+    /** A gesture is past the activation threshold (distinguishes a drag from a click). */
+    active: boolean;
+    /** Pointer position at the pointerdown that began the gesture. */
+    start: PointerPoint;
+    /** Latest pointer position. */
+    current: PointerPoint;
+    /** `current - start`, computed on the same update as `current` (never torn). */
+    delta: PointerPoint;
+    /** The captured pointer id, or `null` when idle. */
+    pointerId: number | null;
+    /** Modifier keys at the latest update. */
+    modifiers: PointerModifiers;
+    /** Mouse button that started the gesture (`-1` when idle). */
+    button: number;
+    /** The pointing device: `'mouse' | 'touch' | 'pen'` (`''` when idle). */
+    pointerType: string;
+    /**
+     * The element the gesture started on: the `handleSelector` match when one is
+     * set (so a single delegated listener can tell which child started the drag),
+     * otherwise the listener's element. `null` when idle.
+     */
+    origin: HTMLElement | null;
+};
+type PointerDragOptions = SensorRunOptions & {
+    /**
+     * Element that receives `pointerdown`. An `HTMLElement`, `ElementRef`, or a
+     * `Signal` of one (listeners re-attach when it changes). Defaults to the host
+     * `ElementRef`.
+     */
+    target?: HTMLElement | ElementRef<HTMLElement> | Signal<HTMLElement | ElementRef<HTMLElement> | null | undefined>;
+    /** `'client'` (viewport) or `'page'` coordinates. @default 'client' */
+    coordinateSpace?: 'client' | 'page';
+    /** Pixels the pointer must travel before `active` flips true. @default 3 */
+    activationThreshold?: number;
+    /**
+     * Throttle (ms) for `current`/`delta` updates. @default 16
+     *
+     * Note: a final sub-throttle move right before `pointerup` may not surface on
+     * the throttled view (it coalesces into the terminal idle). Logic that must act
+     * on the *exact* release position should read {@link PointerDragSignal.unthrottled}.
+     */
+    throttle?: number;
+    /** Only start when the pointerdown target matches this selector (delegated handles). */
+    handleSelector?: string;
+    /** Mouse buttons that may start a gesture. @default [0] (primary) */
+    buttons?: number[];
+    /**
+     * Stop the `pointerdown` from propagating once this sensor claims it. Lets an
+     * inner sensor win over an outer one on the same element tree (e.g. a nested
+     * sortable inside another). @default false
+     */
+    stopPropagation?: boolean;
+};
+/** A gesture signal with an `unthrottled` view and an imperative `cancel()`. */
+type PointerDragSignal = Signal<PointerDragState> & {
+    readonly unthrottled: Signal<PointerDragState>;
+    /** Abort the current gesture and reset to idle (e.g. on Escape / programmatically). */
+    cancel: () => void;
+};
+/**
+ * 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
+ * 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;
+ * });
+ * ```
+ */
+declare function pointerDrag(opt?: PointerDragOptions): PointerDragSignal;
+
 /**
  * Creates a read-only signal that tracks the page's visibility state.
  *
@@ -2080,6 +2200,10 @@ type SensorTypedOptions = {
         opt: MousePositionOptions;
         returnType: MousePositionSignal;
     };
+    pointerDrag: {
+        opt: PointerDragOptions;
+        returnType: PointerDragSignal;
+    };
     networkStatus: {
         opt: SensorRunOptions;
         returnType: NetworkStatusSignal;
@@ -2164,6 +2288,15 @@ declare function sensor(type: 'elementSize', options?: SensorTypedOptions['eleme
  * @example const pos = sensor('mousePosition', { coordinateSpace: 'page', throttle: 50 });
  */
 declare function sensor(type: 'mousePosition', options?: SensorTypedOptions['mousePosition']['opt']): MousePositionSignal;
+/**
+ * Creates a sensor signal tracking a pointer drag gesture (down → move → up).
+ * @param type Must be `'pointerDrag'`.
+ * @param options Optional configuration (target, activationThreshold, throttle, …).
+ * @returns A `PointerDragSignal` with `active`/`start`/`current`/`delta`, plus `unthrottled` and `cancel()`.
+ * @see {pointerDrag} for detailed documentation and examples.
+ * @example const drag = sensor('pointerDrag', { activationThreshold: 4 });
+ */
+declare function sensor(type: 'pointerDrag', options?: SensorTypedOptions['pointerDrag']['opt']): PointerDragSignal;
 /**
  * Creates a sensor signal that tracks the browser's online/offline status.
  * @param type Must be `'networkStatus'`.
@@ -2327,6 +2460,32 @@ type ResolvableTarget = EventTargetLike | Signal<EventTargetLike | null>;
 declare function signalFromEvent<TEvent extends Event>(target: ResolvableTarget, eventName: string, initial: TEvent | null, opt?: SignalFromEventOptions): Signal<TEvent | null>;
 declare function signalFromEvent<TEvent extends Event, U>(target: ResolvableTarget, eventName: string, initial: U, project: (event: TEvent) => U, opt?: SignalFromEventOptions): Signal<U>;
 
+/**
+ * @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}.
+ */
+declare const LEAF: unique symbol;
+/**
+ * Reports whether a store node is currently a **leaf** — a terminal value the store does not
+ * descend into (a primitive, `Date`, `RegExp`, {@link opaque} object, class instance, or a
+ * `null`/`undefined` hole when vivification is off) rather than a record/array substore.
+ *
+ * Leaf-ness reflects the node's **live** value: the probe is reactive and memoized, so calling
+ * `isLeaf` inside a `computed`/`effect` re-evaluates when the node's shape changes.
+ *
+ * @internal Exposed for advanced/niche interop only — not part of the supported public surface
+ * and may change without a major version bump.
+ *
+ * @example
+ * const s = store({ name: 'Ada', address: { city: 'London' } });
+ * isLeaf(s.name);    // true
+ * isLeaf(s.address); // false — a substore
+ */
+declare function isLeaf<T = unknown>(value: unknown): value is Signal<T> & {
+    readonly [LEAF]: () => boolean;
+};
+
 /**
  * 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
@@ -2360,31 +2519,6 @@ declare function opaque<T extends object>(value: T): Opaque<T>;
  * }
  */
 declare function isOpaque<T = object>(value: unknown): value is Opaque<T>;
-/**
- * @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}.
- */
-declare const LEAF: unique symbol;
-/**
- * Reports whether a store node is currently a **leaf** — a terminal value the store does not
- * descend into (a primitive, `Date`, `RegExp`, {@link opaque} object, class instance, or a
- * `null`/`undefined` hole when vivification is off) rather than a record/array substore.
- *
- * Leaf-ness reflects the node's **live** value: the probe is reactive and memoized, so calling
- * `isLeaf` inside a `computed`/`effect` re-evaluates when the node's shape changes.
- *
- * @internal Exposed for advanced/niche interop only — not part of the supported public surface
- * and may change without a major version bump.
- *
- * @example
- * const s = store({ name: 'Ada', address: { city: 'London' } });
- * isLeaf(s.name);    // true
- * isLeaf(s.address); // false — a substore
- */
-declare function isLeaf<T = unknown>(value: unknown): value is Signal<T> & {
-    readonly [LEAF]: () => boolean;
-};
 /**
  * An object marked via {@link opaque} — the store treats it as an indivisible leaf
  * (like a `Date`), returning it whole instead of deep-proxying its keys.
@@ -2396,16 +2530,27 @@ type Opaque<T> = T & {
 type UnwrapOpaque<T> = T extends {
     readonly [OPAQUE]: true;
 } ? Omit<T, typeof OPAQUE> : T;
+
 type BaseType = string | number | boolean | symbol | bigint | undefined | null | Function | Date | RegExp | {
     readonly [OPAQUE]: true;
 };
 type Key = string | number;
 type AnyRecord = Record<Key, any>;
 /**
- * @internal
- * Validates whether a value is a Signal Store.
+ * @internal Resolves to `true` only for `any`. In a conditional type, `any` distributes across
+ * *both* branches (`unknown | object`), and `unknown | X` collapses to `unknown` — which would
+ * erase a store's property access and `extend`. Guarding on this routes an `any`-typed store to
+ * the full object shape instead.
  */
-declare function isStore<T>(value: unknown): value is SignalStore<T>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * @internal Flattens an intersection (`A & B & C`) into a single object literal so editor
+ * tooltips show the resolved members instead of the raw intersection chain. Display-only —
+ * structurally identical to its input.
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 type SignalArrayStore<T extends any[]> = Signal<T> & {
     readonly [index: number]: SignalStore<T[number]>;
     readonly length: Signal<number>;
@@ -2423,25 +2568,11 @@ type MutableArrayStore<T extends any[]> = MutableSignal<T> & {
     readonly length: Signal<number>;
     [Symbol.iterator](): Iterator<MutableSignalStore<T[number]>>;
 };
-/**
- * @internal Resolves to `true` only for `any`. In a conditional type, `any` distributes across
- * *both* branches (`unknown | object`), and `unknown | X` collapses to `unknown` — which would
- * erase a store's property access and `extend`. Guarding on this routes an `any`-typed store to
- * the full object shape instead.
- */
-type IsAny<T> = 0 extends 1 & T ? true : false;
-/**
- * @internal Flattens an intersection (`A & B & C`) into a single object literal so editor
- * tooltips show the resolved members instead of the raw intersection chain. Display-only —
- * structurally identical to its input.
- */
-type Simplify<T> = {
-    [K in keyof T]: T[K];
-} & {};
 /** @internal The object shape of a readonly store: a child store per key, plus `extend`. */
 type SignalStoreObject<T> = Simplify<Readonly<{
     [K in keyof Required<T>]: SignalStore<NonNullable<T>[K]>;
 }> & {
+    /** @deprecated Use the standalone `extendStore(store, …)`; the `extend` key is removed next minor. */
     readonly extend: {
         <L extends AnyRecord>(source: Signal<L>): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
         <L extends AnyRecord>(props: L): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
@@ -2451,6 +2582,7 @@ type SignalStoreObject<T> = Simplify<Readonly<{
 type WritableSignalStoreObject<T> = Simplify<Readonly<{
     [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
 }> & {
+    /** @deprecated Use the standalone `extendStore(store, …)`; the `extend` key is removed next minor. */
     readonly extend: {
         <L extends AnyRecord>(source: WritableSignal<L>): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
         <L extends AnyRecord>(props: L): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
@@ -2460,6 +2592,7 @@ type WritableSignalStoreObject<T> = Simplify<Readonly<{
 type MutableSignalStoreObject<T> = Simplify<Readonly<{
     [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
 }> & {
+    /** @deprecated Use the standalone `extendStore(store, …)`; the `extend` key is removed next minor. */
     readonly extend: {
         <L extends AnyRecord>(source: MutableSignal<L>): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
         <L extends AnyRecord>(props: L): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
@@ -2478,9 +2611,65 @@ type MutableSignalStore<T> = MutableSignal<UnwrapOpaque<T>> & {
 } & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
 } : NonNullable<T> extends any[] ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
-declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): MutableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): WritableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): SignalStore<T>;
+
+declare const STORE_SHARED_GLOBALS: unique symbol;
+/**
+ * @internal
+ * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
+ */
+type ProxyCache = WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
+/**
+ * @internal
+ * Prunes a cache entry once its proxy is reclaimed by the GC.
+ */
+type ProxyCleanupRegistry = FinalizationRegistry<{
+    target: object;
+    prop: PropertyKey;
+}>;
+/**
+ * @internal
+ * Validates whether a value is a Signal Store.
+ */
+declare function isStore<T>(value: unknown): value is SignalStore<T>;
+
+type toStoreOptions = {
+    injector?: Injector;
+    /**
+     * Opt-in autovivification: when writing through a `null`/`undefined` path, create the
+     * missing intermediate containers instead of dropping the write. Off by default.
+     *
+     * Levels whose current value is a known object/array re-vivify as that same shape — the
+     * knowledge is captured when the path is first accessed and cached, so it holds even after
+     * the value is later nulled. This option governs only genuinely-unknown (currently
+     * `null`/`undefined`) levels: `'auto'` (an array for index keys, an object otherwise), an
+     * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
+     */
+    vivify?: Vivify;
+    /**
+     * Performance opt-in: promise that no node ever switches between leaf and substore (i.e. no
+     * unions mixing a primitive with an object/array). With this on, each node's leaf-ness is
+     * resolved once on the first {@link isLeaf} probe and cached as a constant, skipping the
+     * reactive `computed`. If a node's shape does change anyway, {@link isLeaf} keeps its first
+     * answer. Off by default.
+     */
+    noUnionLeaves?: boolean;
+    /**
+     * @internal
+     * Shared cleanup singletons, they get injected/passed automatically
+     */
+    [STORE_SHARED_GLOBALS]?: {
+        cache: ProxyCache;
+        registry: ProxyCleanupRegistry;
+    };
+};
+type StoreOptions<T> = CreateSignalOptions<T> & toStoreOptions;
+declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, options?: toStoreOptions): MutableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, options?: toStoreOptions): WritableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: Signal<T>, options?: toStoreOptions): SignalStore<T>;
+type ExtendStoreOptions = Omit<toStoreOptions, 'vivify' | 'noUnionLeaves' | typeof STORE_SHARED_GLOBALS>;
+declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: MutableSignalStore<T>, source: MutableSignal<L> | L, options?: ExtendStoreOptions): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: WritableSignalStore<T>, source: WritableSignal<L> | L, options?: ExtendStoreOptions): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: SignalStore<T>, source: Signal<L> | L, options?: ExtendStoreOptions): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
@@ -2594,22 +2783,13 @@ type Fork<T> = {
  * leaves compare by value, so equal primitives are correctly seen as unchanged.
  */
 declare function merge3<T>(ancestor: T, mine: T, theirs: T): T;
-declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: {
+/**
+ * ForkStoreOptions, vivify/noUnionLeaves should remain the same & are automatically inherited, override carefully (advanced usecases)
+ */
+type ForkStoreOptions<T> = toStoreOptions & {
     strategy?: ForkStrategy<T>;
-    injector?: Injector;
-    /**
-     * Store config for the FORK's store — NOT inherited from `base` (it's closed over inside
-     * the base's `toStore` and can't be read back). If the base was created with these, pass
-     * the same values or the fork's write semantics will differ:
-     *  - `vivify`: without it, a write through a `null`/`undefined` path is silently dropped on
-     *    the fork even though the base would have created the container. Match the base.
-     *  - `noUnionLeaves`: a perf promise; off just means the slower reactive leaf-probe. NOTE it
-     *    is a whole-store guarantee — a fork that flips a node's type (leaf↔substore) violates it,
-     *    and on `commit` the base receives the flipped value with stale cached leaf-ness.
-     */
-    vivify?: Vivify;
-    noUnionLeaves?: boolean;
-}): Fork<T>;
+};
+declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): Fork<T>;
 
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
@@ -2677,6 +2857,18 @@ type CreateStoredOptions<T> = CreateSignalOptions<T> & {
      * Optional validator, which is called on load of value. Store will be set to fallback if value is false
      */
     validate?: (value: T) => boolean;
+    /**
+     * Opt-in pause: gate the persistence effect on an ambient Activity boundary (`true`), a custom
+     * predicate, or `false` (default — no pausing). While paused the value stays live; persistence is
+     * skipped and flushes the latest value on resume. The inbound `storage` listener stays live.
+     * See {@link PauseOption}.
+     */
+    pause?: PauseOption;
+    /**
+     * Injector used when `stored` is created outside an injection context, and to resolve the ambient
+     * pause boundary when `pause` is `true`.
+     */
+    injector?: Injector;
 };
 /**
  * A specialized `WritableSignal` returned by the `stored()` function.
@@ -2748,13 +2940,21 @@ type StoredSignal<T> = WritableSignal<T> & {
  * }
  * ```
  */
-declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, pause, injector: providedInjector, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 
 type LegacySyncSignalOptions = {
     id?: string;
 };
 type SyncSignalOptions = {
     id: string;
+    /**
+     * Injector used when `tabSync` is called outside an injection context.
+     *
+     * NOTE: `tabSync` is intentionally NOT pausable. Pausing the outbound broadcast would let its
+     * mount-time echo guard swallow a value changed while hidden, so other tabs would silently miss
+     * it — a cross-tab consistency gap not worth the negligible saving. The channel stays live.
+     */
+    injector?: Injector;
 };
 /**
  * @example tabSync(signal('dark'), { id: 'theme' })
@@ -2803,12 +3003,16 @@ type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
 /**
  * A specialized `WritableSignal` whose publicly readable value updates are throttled.
  *
- * It provides access to the underlying, non-throttled signal via the `original` property.
+ * Provides access to the underlying, non-throttled signal via `original`, and a
+ * `flush()` that emits the current value immediately (clearing any open window) —
+ * useful for terminal transitions that shouldn't wait for the trailing edge.
  *
  * @template T The type of value held by the signal.
- * @see {DebouncedSignal} as the output type has the same structure.
  */
-type ThrottledSignal<T> = DebouncedSignal<T>;
+type ThrottledSignal<T> = DebouncedSignal<T> & {
+    /** Emit the latest value now, bypassing the remaining throttle window. */
+    flush: () => void;
+};
 /**
  * A convenience function that creates and throttles a new `WritableSignal` in one step.
  *
@@ -2829,7 +3033,7 @@ type ThrottledSignal<T> = DebouncedSignal<T>;
  * // With a trailing-edge throttle, the final value 'c' would be set
  * // after the 500ms cooldown.
  */
-declare function throttled<T>(initial: T, opt?: CreateThrottledOptions<T>): DebouncedSignal<T>;
+declare function throttled<T>(initial: T, opt?: CreateThrottledOptions<T>): ThrottledSignal<T>;
 /**
  * Wraps an existing `WritableSignal` to create a new one whose readable value is throttled.
  *
@@ -3045,5 +3249,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, Fork, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };
+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 };
+export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };