@mmstack/primitives 22.1.1 → 22.2.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@mmstack/primitives",
-  "version": "22.1.1",
+  "version": "22.2.0",
   "keywords": [
     "angular",
     "signals",
     "debounce",
-    "mapArray",
+    "indexArray",
     "primitives"
   ],
   "license": "MIT",

package/types/mmstack-primitives.d.ts

@@ -25,7 +25,7 @@ type CreateChunkedOptions<T> = {
 /**
  * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
  *
- * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `duration`.
+ * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `delay`.
  *
  * @template T The type of items in the array.
  * @param source A `Signal` or a function that returns an array of items to be processed in chunks.
@@ -34,7 +34,7 @@ type CreateChunkedOptions<T> = {
  *
  * @example
  * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
- * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ * const chunkedList = chunked(largeList, { chunkSize: 100, delay: 100 });
  */
 declare function chunked<T>(source: Signal<T[]> | (() => T[]), options?: CreateChunkedOptions<T>): Signal<T[]>;
 
@@ -141,8 +141,9 @@ declare function pausableEffect(effectFn: (registerCleanup: EffectCleanupRegiste
 /**
  * Like `signal`, but pausable. While paused, READS hold the last value; writes still land on the
  * underlying signal and surface on resume. Built on the `keepPrevious`/`hold` shape — a
- * `linkedSignal` gated on the pause predicate, with `set`/`update`/`asReadonly` forwarded to the
- * source signal. With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
+ * `linkedSignal` gated on the pause predicate, with `set`/`update` forwarded to the source signal.
+ * `asReadonly()` returns the held (gated) view, so both views of the signal agree while paused.
+ * With no `pause` option it defaults to the ambient `PAUSED_CONTEXT`; `pause: false`
  * makes it a plain `signal` — no `linkedSignal` is created.
  *
  * NOTE: while paused, `set(x)` followed by a read returns the *held* (pre-pause) value, not `x` — the
@@ -176,6 +177,11 @@ type TransitionRef = {
  *
  * Must be called in an injection context. This is the *async* generalization (Tier 2): it adds
  * no rendering cost and needs no fork — holding direct/sync readers is a separate, deferred tier.
+ *
+ * Caveat: work must go in flight by the first post-write render to be awaited. A loader that
+ * starts later (a debounced request signal, a chained/deferred resource) is not attributable to
+ * this transition — the no-async fallback will have already resolved `done`. Trigger such work
+ * eagerly inside `fn`, or coordinate it separately.
  */
 declare function injectStartTransition(): (fn: () => void) => TransitionRef;
 
@@ -244,6 +250,20 @@ declare function createTransitionScope(): TransitionScope;
 /** Provide a fresh transition scope at a boundary so its subtree's resources are tracked independently. */
 declare function provideTransitionScope(): Provider;
 declare function injectTransitionScope(): TransitionScope;
+/**
+ * A transition scope that can be re-pointed at a delegate target at runtime. Reads and
+ * commit/hold follow the current target; `add`/`remove` pin to the target that was current
+ * at add-time, so re-pointing between a resource's registration and its destroy-time removal
+ * never strands it in the wrong scope. With no target it behaves as a plain own-scope.
+ */
+type ForwardingTransitionScope = TransitionScope & {
+    setTarget(target: TransitionScope | null): void;
+};
+declare function createForwardingScope(): ForwardingTransitionScope;
+/** Provide a forwarding transition scope at a boundary (used by the transition outlet). */
+declare function provideForwardingTransitionScope(): Provider;
+/** Read the transition scope reachable from `injector`, or null if none is provided there. */
+declare function getTransitionScope(injector: Injector): TransitionScope | null;
 /**
  * Returns a register function bound to the nearest transition scope: it adds a resource
  * to the scope and removes it when the caller's injection context is destroyed. Pass any
@@ -331,6 +351,11 @@ type TransactionRef = {
  * The writes land on LIVE state immediately (so derived variables and connector requests see the
  * new values and refetch); only the *display* is held, via `scope.hold`. Must run in an injection
  * context.
+ *
+ * Caveat: work must go in flight by the first post-write render to be part of the transaction. A
+ * loader that starts later (a debounced request signal, a chained/deferred resource) is not
+ * attributable to it — the no-async fallback will have already committed and released the hold,
+ * after which `abort()` is a no-op. Trigger such work eagerly inside `fn`.
  */
 declare function injectStartTransaction(): (fn: () => void) => TransactionRef;
 
@@ -524,7 +549,7 @@ declare function mutable<T>(initial: T, opt?: CreateSignalOptions<T>): MutableSi
  *   myMutableSignal.mutate(x => x + 1); // This is safe.
  * }
  */
-declare function isMutable<T = any>(value: WritableSignal<T>): value is MutableSignal<T>;
+declare function isMutable<T = unknown>(value: WritableSignal<T>): value is MutableSignal<T>;
 
 /** @internal Narrows `'array'` so it is only assignable when `T` is an array type. */
 type VivifyArray<T> = T extends any[] ? 'array' : never;
@@ -818,7 +843,7 @@ type Frame = {
  * ]);
  *
  * // The fine-grained mapped list
- * const mappedUsers = mapArray(
+ * const mappedUsers = indexArray(
  *   users,
  *   (userSignal, index) => {
  *     // 1. Create a fine-grained SIDE EFFECT for *this item*
@@ -839,7 +864,7 @@ type Frame = {
  *     };
  *   },
  *   {
- *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     // 3. Tell indexArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
  *     onDestroy: (mappedItem) => {
  *       mappedItem.destroyEffect();
  *     }
@@ -1085,7 +1110,7 @@ type SignalPipe<In> = {
  * @see {@link SignalPipe}
  * @example
  * ```ts
- * import { piped } from '@ngrx/signals';
+ * import { piped } from '@mmstack/primitives';
  *
  * const count = piped(1);
  *
@@ -1248,7 +1273,7 @@ declare const scan: <T, R>(reducer: (acc: R, curr: T) => R, seed: R) => Operator
  */
 declare function pipeable<TSig extends Signal<any>>(signal: TSig): PipeableSignal<SignalValue<TSig>, TSig>;
 /**
- * Create a new **writable** signal and return it as a `PipableSignal`.
+ * Create a new **writable** signal and return it as a `PipeableSignal`.
  *
  * The returned value is a `WritableSignal<T>` with `.set`, `.update`, `.asReadonly`
  * still available (via intersection type), plus a chainable `.pipe(...)`.
@@ -1382,6 +1407,22 @@ declare function pooledSet<T extends Set<unknown>, U = T>(opt: CreateProvidedPoo
 declare function pooledMap<T extends Map<unknown, unknown>, U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
 declare function pooledMap<T extends Map<unknown, unknown>, U = T>(opt: CreateProvidedPooledOptions<T, U>): Signal<U>;
 
+/**
+ * Options shared by every sensor: an optional `debugName` for the produced signal(s) and an
+ * optional `Injector` that lifts the injection-context requirement.
+ */
+type SensorRunOptions = {
+    /** Optional debug name for the produced signal(s). */
+    debugName?: string;
+    /**
+     * Injector used to resolve the sensor's dependencies (`PLATFORM_ID`, `DestroyRef`, default
+     * `ElementRef` targets, ...). Provide it when creating the sensor outside an injection
+     * context — e.g. in `ngOnInit`, an event handler, or an effect body. When omitted, the
+     * sensor must be created in an injection context (a constructor / field initializer).
+     */
+    injector?: Injector;
+};
+
 type BatteryStatus = {
     readonly level: number;
     readonly charging: boolean;
@@ -1403,7 +1444,7 @@ type BatteryStatus = {
  * });
  * ```
  */
-declare function batteryStatus(debugName?: string): Signal<BatteryStatus | null>;
+declare function batteryStatus(opt?: string | SensorRunOptions): Signal<BatteryStatus | null>;
 
 type ClipboardSignal = Signal<string> & {
     /**
@@ -1425,7 +1466,7 @@ type ClipboardSignal = Signal<string> & {
  * in browsers that gate it. Errors from `navigator.clipboard.readText` are
  * swallowed silently to keep the signal value stable.
  */
-declare function clipboard(debugName?: string): ClipboardSignal;
+declare function clipboard(opt?: string | SensorRunOptions): ClipboardSignal;
 
 /**
  * Represents the size of an element.
@@ -1437,10 +1478,7 @@ interface ElementSize {
 /**
  * Options for configuring the `elementSize` sensor.
  */
-type ElementSizeOptions = ResizeObserverOptions & {
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
+type ElementSizeOptions = ResizeObserverOptions & SensorRunOptions;
 type ElementSizeSignal = Signal<ElementSize | undefined>;
 /**
  * Creates a read-only signal that tracks the size of a target DOM element.
@@ -1466,10 +1504,7 @@ declare function elementSize(target?: ElementRef<Element> | Element | Signal<Ele
  * Options for configuring the `elementVisibility` sensor, extending
  * standard `IntersectionObserverInit` options.
  */
-type ElementVisibilityOptions = IntersectionObserverInit & {
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
+type ElementVisibilityOptions = IntersectionObserverInit & SensorRunOptions;
 type ElementVisibilitySignal = Signal<IntersectionObserverEntry | undefined> & {
     readonly visible: Signal<boolean>;
 };
@@ -1546,17 +1581,15 @@ type FocusWithinTarget = ElementRef<Element> | Element | Signal<ElementRef<Eleme
  * }
  * ```
  */
-declare function focusWithin(target?: FocusWithinTarget): Signal<boolean>;
+declare function focusWithin(target?: FocusWithinTarget, opt?: SensorRunOptions): Signal<boolean>;
 
-type GeolocationOptions = PositionOptions & {
+type GeolocationOptions = PositionOptions & SensorRunOptions & {
     /**
      * If `true`, uses `navigator.geolocation.watchPosition` and updates the
      * signal continuously. Otherwise a single `getCurrentPosition` call is made.
      * @default false
      */
     watch?: boolean;
-    /** Optional debug name for the produced signal. */
-    debugName?: string;
 };
 type GeolocationSignal = Signal<GeolocationPosition | null> & {
     readonly error: Signal<GeolocationPositionError | null>;
@@ -1577,7 +1610,7 @@ type GeolocationSignal = Signal<GeolocationPosition | null> & {
  */
 declare function geolocation(opt?: GeolocationOptions): GeolocationSignal;
 
-type IdleOptions = {
+type IdleOptions = SensorRunOptions & {
     /**
      * Milliseconds of user inactivity before the signal flips to `true`.
      * @default 60_000
@@ -1588,11 +1621,12 @@ type IdleOptions = {
      * @default ['mousemove','keydown','touchstart','scroll','visibilitychange']
      */
     events?: string[];
-    /** Optional debug name for the produced signal. */
-    debugName?: string;
 };
 type IdleSignal = Signal<boolean> & {
-    /** Timestamp of the last idle/active transition. */
+    /**
+     * Timestamp of the last idle/active transition. Before any transition has occurred it
+     * holds the sensor's creation time, not an actual transition.
+     */
     readonly since: Signal<Date>;
 };
 /**
@@ -1656,7 +1690,7 @@ declare function idle(opt?: IdleOptions): IdleSignal;
  * }
  * ```
  */
-declare function mediaQuery(query: string, debugName?: string): Signal<boolean>;
+declare function mediaQuery(query: string, opt?: string | SensorRunOptions): Signal<boolean>;
 /**
  * Creates a read-only signal that tracks the user's OS/browser preference
  * for a dark color scheme using the `(prefers-color-scheme: dark)` media query.
@@ -1678,7 +1712,7 @@ declare function mediaQuery(query: string, debugName?: string): Signal<boolean>;
  * });
  * ```
  */
-declare function prefersDarkMode(debugName?: string): Signal<boolean>;
+declare function prefersDarkMode(opt?: string | SensorRunOptions): Signal<boolean>;
 /**
  * Creates a read-only signal that tracks the user's OS/browser preference
  * for reduced motion using the `(prefers-reduced-motion: reduce)` media query.
@@ -1704,7 +1738,7 @@ declare function prefersDarkMode(debugName?: string): Signal<boolean>;
  * });
  * ```
  */
-declare function prefersReducedMotion(debugName?: string): Signal<boolean>;
+declare function prefersReducedMotion(opt?: string | SensorRunOptions): Signal<boolean>;
 
 type MousePosition = {
     x: number;
@@ -1713,13 +1747,15 @@ type MousePosition = {
 /**
  * Options for configuring the `mousePosition` sensor.
  */
-type MousePositionOptions = {
+type MousePositionOptions = SensorRunOptions & {
     /**
      * The target element to listen for mouse movements on.
-     * Can be `window`, `document`, an `HTMLElement`, or an `ElementRef<HTMLElement>`.
+     * Can be `window`, `document`, an `HTMLElement`, an `ElementRef<HTMLElement>`, or a
+     * `Signal` resolving to one (e.g. a `viewChild` result) — listeners re-attach when the
+     * signal's element changes, and nothing is tracked while it is `null`/`undefined`.
      * @default window
      */
-    target?: Window | Document | HTMLElement | ElementRef<HTMLElement>;
+    target?: Window | Document | HTMLElement | ElementRef<HTMLElement> | Signal<HTMLElement | ElementRef<HTMLElement> | null | undefined>;
     /**
      * Defines the coordinate system for the reported position.
      * - `'client'`: Coordinates relative to the viewport (`clientX`, `clientY`).
@@ -1733,10 +1769,6 @@ type MousePositionOptions = {
      * @default false
      */
     touch?: boolean;
-    /**
-     * Optional debug name for the internal signal.
-     */
-    debugName?: string;
     /**
      * Optional delay in milliseconds to throttle the updates.
      * @default 100
@@ -1790,7 +1822,10 @@ declare function mousePosition(opt?: MousePositionOptions): MousePositionSignal;
  * It's a boolean signal with an attached `since` signal.
  */
 type NetworkStatusSignal = Signal<boolean> & {
-    /** A signal tracking the timestamp of the last status change. */
+    /**
+     * A signal tracking the timestamp of the last status change. Before any change has
+     * occurred it holds the sensor's creation time, not an actual transition.
+     */
     readonly since: Signal<Date>;
 };
 /**
@@ -1800,7 +1835,8 @@ type NetworkStatusSignal = Signal<boolean> & {
  * An additional `since` signal is attached, tracking when the status last changed.
  * It's SSR-safe and automatically cleans up its event listeners.
  *
- * @param debugName Optional debug name for the signal.
+ * @param opt Optional debug name for the signal, or a {@link SensorRunOptions} object
+ * (with an optional `injector` for creation outside an injection context).
  * @returns A `NetworkStatusSignal` instance.
  *
  * @example
@@ -1811,14 +1847,20 @@ type NetworkStatusSignal = Signal<boolean> & {
  * });
  * ```
  */
-declare function networkStatus(debugName?: string): NetworkStatusSignal;
+declare function networkStatus(opt?: string | SensorRunOptions): NetworkStatusSignal;
 
-type ScreenOrientation = {
+type ScreenOrientationState = {
     /** Angle in degrees relative to the natural orientation. */
     readonly angle: number;
     /** One of the four `OrientationType` strings. */
     readonly type: OrientationType;
 };
+/**
+ * @deprecated Use {@link ScreenOrientationState} instead — this name shadows the DOM's global
+ * `ScreenOrientation` interface in any module that imports it, silently changing the meaning of
+ * `screen.orientation`-related typings there.
+ */
+type ScreenOrientation = ScreenOrientationState;
 /**
  * Creates a read-only signal that tracks `screen.orientation`.
  *
@@ -1834,7 +1876,7 @@ type ScreenOrientation = {
  * });
  * ```
  */
-declare function orientation(debugName?: string): Signal<ScreenOrientation>;
+declare function orientation(opt?: string | SensorRunOptions): Signal<ScreenOrientationState>;
 
 /**
  * Creates a read-only signal that tracks the page's visibility state.
@@ -1844,7 +1886,8 @@ declare function orientation(debugName?: string): Signal<ScreenOrientation>;
  * The primitive is SSR-safe and automatically cleans up its event listeners
  * when the creating context is destroyed.
  *
- * @param debugName Optional debug name for the signal.
+ * @param opt Optional debug name for the signal, or a {@link SensorRunOptions} object
+ * (with an optional `injector` for creation outside an injection context).
  * @returns A read-only `Signal<DocumentVisibilityState>`. On the server,
  * it returns a static signal with a value of `'visible'`.
  *
@@ -1872,7 +1915,7 @@ declare function orientation(debugName?: string): Signal<ScreenOrientation>;
  * }
  * ```
  */
-declare function pageVisibility(debugName?: string): Signal<DocumentVisibilityState>;
+declare function pageVisibility(opt?: string | SensorRunOptions): Signal<DocumentVisibilityState>;
 
 /**
  * Represents the scroll position.
@@ -1886,21 +1929,21 @@ type ScrollPosition = {
 /**
  * Options for configuring the `scrollPosition` sensor.
  */
-type ScrollPositionOptions = {
+type ScrollPositionOptions = SensorRunOptions & {
     /**
      * The target to listen for scroll events on.
-     * Can be `window` (for page scroll) or an `HTMLElement`/`ElementRef<HTMLElement>`.
+     * Can be `window` (for page scroll), an `HTMLElement`/`ElementRef<HTMLElement>`, or a
+     * `Signal` resolving to one (e.g. a `viewChild` result) — listeners re-attach when the
+     * signal's element changes, and nothing is tracked while it is `null`/`undefined`.
      * @default window
      */
-    target?: Window | HTMLElement | ElementRef<HTMLElement>;
+    target?: Window | HTMLElement | ElementRef<HTMLElement> | Signal<HTMLElement | ElementRef<HTMLElement> | null | undefined>;
     /**
      * Optional delay in milliseconds to throttle the updates.
      * Scroll events can fire very rapidly.
      * @default 100 // A common default for scroll throttling
      */
     throttle?: number;
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
 };
 /**
  * A specialized Signal that tracks scroll position.
@@ -1931,26 +1974,17 @@ type ScrollPositionSignal = Signal<ScrollPosition> & {
  * selector: 'app-scroll-tracker',
  * template: `
  * <p>Window Scroll: X: {{ windowScroll().x }}, Y: {{ windowScroll().y }}</p>
- * <div #scrollableDiv style="height: 200px; width: 200px; overflow: auto; border: 1px solid black;">
- * <div style="height: 400px; width: 400px;">Scroll me!</div>
- * </div>
- * @if (divScroll()) {
- * <p>Div Scroll: X: {{ divScroll().x }}, Y: {{ divScroll().y }}</p>
- * }
+ * <p>Host Scroll: X: {{ hostScroll().x }}, Y: {{ hostScroll().y }}</p>
  * `
  * })
  * export class ScrollTrackerComponent {
  * readonly windowScroll = scrollPosition(); // Defaults to window
+ * // Signal targets (e.g. viewChild) attach once the element exists:
  * readonly scrollableDiv = viewChild<ElementRef<HTMLDivElement>>('scrollableDiv');
- * readonly divScroll = scrollPosition({ target: this.scrollableDiv() }); // Example with element target
+ * readonly divScroll = scrollPosition({ target: this.scrollableDiv });
  *
  * constructor() {
- * effect(() => {
- * console.log('Window scrolled to:', this.windowScroll());
- * if (this.divScroll()) {
- * console.log('Div scrolled to:', this.divScroll());
- * }
- * });
+ * effect(() => console.log('Window scrolled to:', this.windowScroll()));
  * }
  * }
  * ```
@@ -1967,13 +2001,9 @@ type WindowSize = {
     readonly height: number;
 };
 /**
- * Options for configuring the `mousePosition` sensor.
+ * Options for configuring the `windowSize` sensor.
  */
-type WindowSizeOptions = {
-    /**
-     * Optional debug name for the internal signal.
-     */
-    debugName?: string;
+type WindowSizeOptions = SensorRunOptions & {
     /**
      * Optional delay in milliseconds to throttle the updates.
      * @default 100
@@ -2050,27 +2080,19 @@ type SensorTypedOptions = {
         returnType: MousePositionSignal;
     };
     networkStatus: {
-        opt: {
-            debugName?: string;
-        };
+        opt: SensorRunOptions;
         returnType: NetworkStatusSignal;
     };
     pageVisibility: {
-        opt: {
-            debugName?: string;
-        };
+        opt: SensorRunOptions;
         returnType: Signal<DocumentVisibilityState>;
     };
     darkMode: {
-        opt: {
-            debugName?: string;
-        };
+        opt: SensorRunOptions;
         returnType: Signal<boolean>;
     };
     reducedMotion: {
-        opt: {
-            debugName?: string;
-        };
+        opt: SensorRunOptions;
         returnType: Signal<boolean>;
     };
     scrollPosition: {
@@ -2082,9 +2104,8 @@ type SensorTypedOptions = {
         returnType: WindowSizeSignal;
     };
     mediaQuery: {
-        opt: {
+        opt: SensorRunOptions & {
             query: string;
-            debugName?: string;
         };
         returnType: Signal<boolean>;
     };
@@ -2093,21 +2114,15 @@ type SensorTypedOptions = {
         returnType: GeolocationSignal;
     };
     clipboard: {
-        opt: {
-            debugName?: string;
-        };
+        opt: SensorRunOptions;
         returnType: ClipboardSignal;
     };
     orientation: {
-        opt: {
-            debugName?: string;
-        };
-        returnType: Signal<ScreenOrientation>;
+        opt: SensorRunOptions;
+        returnType: Signal<ScreenOrientationState>;
     };
     batteryStatus: {
-        opt: {
-            debugName?: string;
-        };
+        opt: SensorRunOptions;
         returnType: Signal<BatteryStatus | null>;
     };
     idle: {
@@ -2115,8 +2130,7 @@ type SensorTypedOptions = {
         returnType: IdleSignal;
     };
     focusWithin: {
-        opt: {
-            debugName?: string;
+        opt: SensorRunOptions & {
             target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
         };
         returnType: Signal<boolean>;
@@ -2188,12 +2202,12 @@ declare function sensor(type: 'reducedMotion' | 'reduced-motion', options?: Sens
 /**
  * Creates a sensor signal that tracks the provided media query.
  * @param type Must be `'mediaQuery'`.
- * @param options Optional configuration for the media query sensor, including `query` and `debugName`.
+ * @param options Required configuration for the media query sensor — `query` is mandatory, `debugName` optional.
  * @returns A `Signal<boolean>` which is `true` if the media query currently matches.
  * @see {mediaQuery} for detailed documentation and examples.
  * @example const isDesktop = sensor('mediaQuery', { query: '(min-width: 1024px)' });
  */
-declare function sensor(type: 'mediaQuery', options?: SensorTypedOptions['mediaQuery']['opt']): Signal<boolean>;
+declare function sensor(type: 'mediaQuery', options: SensorTypedOptions['mediaQuery']['opt']): Signal<boolean>;
 /**
  * Creates a sensor signal that tracks the browser window's inner dimensions (width and height).
  * @param type Must be `'windowSize'`.
@@ -2226,7 +2240,7 @@ declare function sensor(type: 'clipboard', options?: SensorTypedOptions['clipboa
  * Creates a sensor signal tracking the screen orientation.
  * @see {orientation}
  */
-declare function sensor(type: 'orientation', options?: SensorTypedOptions['orientation']['opt']): Signal<ScreenOrientation>;
+declare function sensor(type: 'orientation', options?: SensorTypedOptions['orientation']['opt']): Signal<ScreenOrientationState>;
 /**
  * Creates a sensor signal tracking the system battery status.
  * @see {batteryStatus}
@@ -2378,7 +2392,7 @@ type Opaque<T> = T & {
     readonly [OPAQUE]: true;
 };
 /** @internal Strips the opaque brand from the value a leaf signal carries. */
-type UnwrapOpqaue<T> = T extends {
+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 | {
@@ -2450,15 +2464,15 @@ type MutableSignalStoreObject<T> = Simplify<Readonly<{
         <L extends AnyRecord>(props: L): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
     };
 }>;
-type SignalStore<T> = Signal<UnwrapOpqaue<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+type SignalStore<T> = Signal<UnwrapOpaque<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
 } : NonNullable<T> extends any[] ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
-type WritableSignalStore<T> = WritableSignal<UnwrapOpqaue<T>> & {
+type WritableSignalStore<T> = WritableSignal<UnwrapOpaque<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
 } & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
 } : NonNullable<T> extends any[] ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
-type MutableSignalStore<T> = MutableSignal<UnwrapOpqaue<T>> & {
+type MutableSignalStore<T> = MutableSignal<UnwrapOpaque<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
 } & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
     readonly [LEAF]: () => boolean;
@@ -2692,8 +2706,8 @@ type StoredSignal<T> = WritableSignal<T> & {
  *
  * @template T The type of value held by the signal and stored (after serialization).
  * @param fallback The default value of type `T` to use when no value is found in storage
- * or when deserialization fails. The signal's value will never be `null` or `undefined`
- * publicly, it will always revert to this fallback.
+ * or when deserialization fails. A stored value (including a legitimate `null` for a
+ * nullable `T`) always round-trips; the fallback only surfaces when the entry is absent.
  * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.
  * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,
  * but its value is persisted. It includes a `.clear()` method to remove the item from storage
@@ -2706,7 +2720,8 @@ type StoredSignal<T> = WritableSignal<T> & {
  * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.
  * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value
  * consistent across browser tabs using the same key. Cleanup is handled automatically
- * using `DestroyRef`.
+ * using `DestroyRef`. Web Storage only: the `storage` event never fires for custom `store`
+ * adapters, so `syncTabs` has no effect with one.
  * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.
  * Setting the signal to the fallback value will store the fallback value, not remove the item.
  *
@@ -2741,7 +2756,7 @@ type SyncSignalOptions = {
     id: string;
 };
 /**
- * @example tabSync(signal('dark), {id: 'theme})
+ * @example tabSync(signal('dark'), { id: 'theme' })
  */
 declare function tabSync<T extends WritableSignal<any>>(sig: T, opt: SyncSignalOptions | string): T;
 /**
@@ -2778,6 +2793,8 @@ type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
     /**
      * If `true`, the throttled signal emits the latest pending value at the end
      * of each cooldown window (only when at least one write occurred during it).
+     * Note: with both `leading` and `trailing` set to `false` the throttled view
+     * never updates (writes still reach `.original`).
      * @default true
      */
     trailing?: boolean;
@@ -2868,6 +2885,10 @@ declare function toWritable<T>(source: Signal<T>, set: (value: T) => void, updat
     /**
      * If `true` (the default), the returned signal will be a computed signal that depends on the source signal.
      * If `false`, the returned signal will be a direct wrapper around the source signal without creating a new computed signal.
+     *
+     * CAUTION: with `pure: false` the `set`/`update`/`asReadonly` methods are patched directly
+     * onto the signal object you passed in — every other holder of that signal sees it become
+     * writable. Only use it with a signal you created and own exclusively.
      * @default true
      */
     pure?: boolean;
@@ -3023,5 +3044,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, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, forkStore, geolocation, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
-export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, Fork, ForkStrategy, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, ReconcileFn, RegisterOptions, ScreenOrientation, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };
+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 };