@mmstack/primitives 21.0.22 → 21.0.24

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -564,7 +564,30 @@ declare const mapArray: typeof indexArray;
  * @param mapFn The mapping function. Receives the item and its index as a Signal.
  * @param options Optional configuration:
  *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
+ *  - `key`: A custom key extractor for identity matching (e.g. `(item) => item.id`)
+ *    when item references change but conceptual identity is preserved.
  * @returns A `Signal<U[]>` containing the mapped array.
+ *
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ * ]);
+ *
+ * const rows = keyArray(
+ *   users,
+ *   (user, index) => ({
+ *     label: computed(() => `#${index()} ${user.name}`),
+ *     id: user.id,
+ *   }),
+ *   { key: (u) => u.id },
+ * );
+ *
+ * // Reordering users() rebuilds index signals only — `rows` entries
+ * // are matched by id and reused, not re-created.
+ * users.set([users()[1], users()[0]]);
+ * ```
  */
 declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v: T, i: Signal<number>) => U, options?: {
     onDestroy?: (value: U) => void;
@@ -579,12 +602,71 @@ declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v:
 type MappedObject<T extends object, U> = {
     [K in keyof T]: U;
 };
+/**
+ * Reactively maps each property of an object signal into a new object,
+ * preserving the same set of keys. For each key, `mapFn` receives a stable
+ * per-key signal — outputs for keys that haven't been added or removed are
+ * reused on subsequent reads. Sibling to {@link indexArray} / {@link keyArray}
+ * but for object records.
+ *
+ * The type of per-key signal passed into `mapFn` depends on the source:
+ * - `MutableSignal<T>` source → `MutableSignal<T[K]>` (in-place mutation)
+ * - `WritableSignal<T>` source → `WritableSignal<T[K]>` (two-way binding)
+ * - read-only `Signal<T>` or `() => T` source → read-only `Signal<T[K]>`
+ *
+ * @typeParam T The object type held by the source signal.
+ * @typeParam U The type produced for each key by `mapFn`.
+ *
+ * @param source A `MutableSignal<T>` whose properties are mapped with full
+ *   in-place mutation capability via the per-key `MutableSignal`.
+ * @param mapFn Receives each key and its per-key `MutableSignal<T[K]>`.
+ * @param options Optional `onDestroy(value)` callback fired when a key is
+ *   removed from the source.
+ * @returns A read-only signal of the mapped object.
+ *
+ * @example
+ * ```ts
+ * const state = mutable({ name: 'Alice', age: 30 });
+ * const view = mapObject(state, (key, prop) => ({
+ *   label: key,
+ *   current: computed(() => prop()),
+ *   onInput: (next: any) => prop.set(next),
+ * }));
+ * view().age.onInput(31);
+ * state(); // { name: 'Alice', age: 31 }
+ * ```
+ */
 declare function mapObject<T extends object, U>(source: MutableSignal<T>, mapFn: <K extends keyof T>(key: K, value: MutableSignal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;
+/**
+ * Reactively maps each property of a `WritableSignal<T>` into a new object.
+ * Each key's per-property signal supports `.set` / `.update` for two-way
+ * binding back into the parent object.
+ *
+ * @example
+ * ```ts
+ * const user = signal({ name: 'Alice', age: 30 });
+ * const inputs = mapObject(user, (key, prop) => ({
+ *   value: prop,
+ *   setValue: (v: any) => prop.set(v),
+ * }));
+ * ```
+ */
 declare function mapObject<T extends object, U>(source: WritableSignal<T>, mapFn: <K extends keyof T>(key: K, value: WritableSignal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;
+/**
+ * Reactively maps each property of a read-only `Signal<T>` (or plain `() => T`
+ * accessor) into a new object. Per-key signals are read-only.
+ *
+ * @example
+ * ```ts
+ * const config = computed(() => ({ theme: 'dark', density: 'compact' }));
+ * const view = mapObject(config, (key, prop) => `${key}: ${prop()}`);
+ * view(); // { theme: 'theme: dark', density: 'density: compact' }
+ * ```
+ */
 declare function mapObject<T extends object, U>(source: (() => T) | Signal<T>, mapFn: <K extends keyof T>(key: K, value: Signal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;
@@ -650,18 +732,137 @@ type PipeableSignal<T, TSig extends Signal<T> = Signal<T>> = TSig & {
  */
 type SignalValue<TSig extends Signal<any>> = TSig extends Signal<infer V> ? V : never;
 
-/** Project with optional equality. Pure & sync. */
+/**
+ * Synchronous projection of a signal value with optional `CreateSignalOptions`
+ * (custom `equal`, `debugName`, etc.). Equivalent to `map` plus the ability to
+ * pass signal options through to the underlying `computed()`.
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, name: 'Alice' });
+ * const name = user.pipe(select((u) => u.name));
+ * name(); // 'Alice'
+ * ```
+ */
 declare const select: <I, O>(projector: (v: I) => O, opt?: CreateSignalOptions<O>) => Operator<I, O>;
-/** Combine with another signal using a projector. */
+/**
+ * Combine the piped signal with another `Signal` using a projector. The result
+ * recomputes whenever either source changes.
+ *
+ * @example
+ * ```ts
+ * const price = piped(10);
+ * const quantity = signal(3);
+ * const total = price.pipe(combineWith(quantity, (p, q) => p * q));
+ * total(); // 30
+ * ```
+ */
 declare const combineWith: <A, B, R>(other: Signal<B>, project: (a: A, b: B) => R, opt?: CreateSignalOptions<R>) => Operator<A, R>;
-/** Only re-emit when equal(prev, next) is false. */
+/**
+ * Suppress emissions while consecutive values are considered equal. The
+ * comparator defaults to `Object.is`; pass a custom one for structural or
+ * key-based equality (e.g. compare by `id` only).
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, lastSeen: Date.now() });
+ * const byId = user.pipe(distinct((a, b) => a.id === b.id));
+ * // byId only re-emits when `id` changes, not on every `lastSeen` update
+ * ```
+ */
 declare const distinct: <T>(equal?: (a: T, b: T) => boolean) => Operator<T, T>;
-/** map to new value */
+/**
+ * Pure synchronous transform from input to output. Equivalent to a `computed()`
+ * that reads the source and returns `fn(value)`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(2);
+ * const doubled = count.pipe(map((n) => n * 2));
+ * doubled(); // 4
+ * ```
+ */
 declare const map: <I, O>(fn: (v: I) => O) => Operator<I, O>;
-/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+/**
+ * Keep only values that pass the predicate. The result holds the last passing
+ * value across emissions; before any value passes, the result is `undefined` —
+ * see {@link filterWith} when you need a non-`undefined` seed.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const clicks = event.pipe(filter((e): e is MouseEvent => e?.type === 'click'));
+ * clicks(); // undefined until a click happens, then the last MouseEvent
+ * ```
+ */
 declare const filter: <T>(predicate: (v: T) => boolean) => Operator<T, T | undefined>;
-/** tap into the value */
-declare const tap: <T>(fn: (v: T) => void) => Operator<T, T>;
+/**
+ * Run a side effect on every emission without altering the signal value. Wraps
+ * Angular's `effect()`, so it must run in an injection context or receive an
+ * explicit `injector`. Use for logging / analytics — not for setting other
+ * signals (that's what regular `effect()` is for).
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * count.pipe(tap((n) => console.log('count:', n)));
+ * count.set(1); // logs 'count: 1'
+ * ```
+ */
+declare const tap: <T>(fn: (v: T) => void, injector?: Injector) => Operator<T, T>;
+/**
+ * Like {@link filter}, but emits `initial` until a value first passes the
+ * predicate. Eliminates the `T | undefined` return type at the cost of an
+ * explicit seed value.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const lastClick = event.pipe(filterWith((e) => e?.type === 'click', null));
+ * lastClick(); // null until the first click, then the most recent click event
+ * ```
+ */
+declare const filterWith: <T>(predicate: (v: T) => boolean, initial: T) => Operator<T, T>;
+/**
+ * Emit `initial` on the first read, then mirror the source on every subsequent
+ * read. Useful for giving a pipeline a sensible seed value before the source
+ * is ready (e.g. loading state).
+ *
+ * @example
+ * ```ts
+ * const data = piped<User | null>(null);
+ * const view = data.pipe(startWith<User | null, 'loading'>('loading'));
+ * view(); // 'loading' on first read, then User | null afterward
+ * ```
+ */
+declare const startWith: <T, U>(initial: U) => Operator<T, T | U>;
+/**
+ * Emit `[prev, curr]` tuples so consumers can react to transitions instead of
+ * raw values. On the first emission `prev` is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * const delta = count.pipe(pairwise(), map(([prev, curr]) => curr - (prev ?? 0)));
+ * count.set(5);
+ * delta(); // 5
+ * ```
+ */
+declare const pairwise: <T>() => Operator<T, [T | undefined, T]>;
+/**
+ * Reduce-like accumulator that folds each emission into a running result.
+ * Behaves like `Array.prototype.reduce` but applied over time, with the
+ * accumulator persisted across emissions.
+ *
+ * @example
+ * ```ts
+ * const delta = piped(0);
+ * const total = delta.pipe(scan((acc, n) => acc + n, 0));
+ * delta.set(5); // total() === 5
+ * delta.set(3); // total() === 8
+ * ```
+ */
+declare const scan: <T, R>(reducer: (acc: R, curr: T) => R, seed: R) => Operator<T, R>;
 
 /**
  * Decorate any `Signal<T>` with a chainable `.pipe(...)` method.
@@ -807,6 +1008,51 @@ 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>;
 
+type BatteryStatus = {
+    readonly level: number;
+    readonly charging: boolean;
+    readonly chargingTime: number;
+    readonly dischargingTime: number;
+};
+/**
+ * Creates a read-only signal that tracks the system battery status using the
+ * Battery Status API. Returns `null` until the underlying `getBattery()`
+ * promise resolves, or permanently when the API is unsupported (Firefox /
+ * Safari at the time of writing). SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const battery = batteryStatus();
+ * effect(() => {
+ *   const b = battery();
+ *   if (b) console.log(`${Math.round(b.level * 100)}% • charging: ${b.charging}`);
+ * });
+ * ```
+ */
+declare function batteryStatus(debugName?: string): Signal<BatteryStatus | null>;
+
+type ClipboardSignal = Signal<string> & {
+    /**
+     * Writes `value` to the system clipboard. Resolves once the write completes;
+     * rejects if the Clipboard API rejects (denied permission, insecure context).
+     */
+    readonly copy: (value: string) => Promise<void>;
+    /** `true` iff the Clipboard API is available in this environment. */
+    readonly isSupported: Signal<boolean>;
+};
+/**
+ * Creates a read-only signal mirroring the system clipboard contents.
+ *
+ * The signal value starts empty and updates whenever a `copy` event fires on
+ * the document (or {@link ClipboardSignal.copy} is invoked from this app).
+ * SSR-safe — returns `''` and `isSupported: false` on the server.
+ *
+ * Note: read access requires the Clipboard API and an active permission grant
+ * 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;
+
 /**
  * Represents the size of an element.
  */
@@ -908,6 +1154,90 @@ type ElementVisibilitySignal = Signal<IntersectionObserverEntry | undefined> & {
  */
 declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;
 
+type FocusWithinTarget = ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
+/**
+ * Creates a read-only signal that tracks whether the focused element is the
+ * target or a descendant of it. Mirrors the CSS `:focus-within` pseudo-class.
+ *
+ * Defaults `target` to the current `ElementRef` so it can be used inline in a
+ * component's `class` field. SSR-safe — returns a constant `false` signal on
+ * the server.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MenuComponent {
+ *   // Defaults to the host element — flips true when focus is inside.
+ *   readonly hasFocus = focusWithin();
+ * }
+ * ```
+ */
+declare function focusWithin(target?: FocusWithinTarget): Signal<boolean>;
+
+type GeolocationOptions = PositionOptions & {
+    /**
+     * 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>;
+    readonly loading: Signal<boolean>;
+};
+/**
+ * Creates a read-only signal that exposes the current geolocation position.
+ *
+ * The returned signal carries `error` and `loading` sub-signals for permission
+ * failures and the in-flight initial fetch respectively. SSR-safe — on the
+ * server the position is `null`, loading is `false`, and no API calls are made.
+ *
+ * @example
+ * ```ts
+ * const where = geolocation({ watch: true, enableHighAccuracy: true });
+ * effect(() => console.log(where()?.coords, where.error()));
+ * ```
+ */
+declare function geolocation(opt?: GeolocationOptions): GeolocationSignal;
+
+type IdleOptions = {
+    /**
+     * Milliseconds of user inactivity before the signal flips to `true`.
+     * @default 60_000
+     */
+    ms?: number;
+    /**
+     * Activity events that reset the idle timer.
+     * @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. */
+    readonly since: Signal<Date>;
+};
+/**
+ * Creates a read-only signal that flips to `true` after a window of user
+ * inactivity. Any of the configured `events` (default: pointer/keyboard/scroll
+ * activity) resets the timer and flips the signal back to `false`.
+ *
+ * SSR-safe — always `false` with a frozen `since` date on the server.
+ *
+ * @example
+ * ```ts
+ * const isAway = idle({ ms: 30_000 });
+ * effect(() => {
+ *   if (isAway()) console.log('idle since', isAway.since());
+ * });
+ * ```
+ */
+declare function idle(opt?: IdleOptions): IdleSignal;
+
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -1098,9 +1428,40 @@ type NetworkStatusSignal = Signal<boolean> & {
  *
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const online = networkStatus();
+ * effect(() => {
+ *   if (!online()) console.log('offline since', online.since());
+ * });
+ * ```
  */
 declare function networkStatus(debugName?: string): NetworkStatusSignal;
 
+type ScreenOrientation = {
+    /** Angle in degrees relative to the natural orientation. */
+    readonly angle: number;
+    /** One of the four `OrientationType` strings. */
+    readonly type: OrientationType;
+};
+/**
+ * Creates a read-only signal that tracks `screen.orientation`.
+ *
+ * SSR-safe — returns a constant `portrait-primary / 0°` signal on the server
+ * and in environments without `screen.orientation` support.
+ *
+ * @example
+ * ```ts
+ * const screenOrientation = orientation();
+ * effect(() => {
+ *   const { type, angle } = screenOrientation();
+ *   console.log(`${type} at ${angle}°`);
+ * });
+ * ```
+ */
+declare function orientation(debugName?: string): Signal<ScreenOrientation>;
+
 /**
  * Creates a read-only signal that tracks the page's visibility state.
  *
@@ -1353,6 +1714,39 @@ type SensorTypedOptions = {
         };
         returnType: Signal<boolean>;
     };
+    geolocation: {
+        opt: GeolocationOptions;
+        returnType: GeolocationSignal;
+    };
+    clipboard: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: ClipboardSignal;
+    };
+    orientation: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<ScreenOrientation>;
+    };
+    batteryStatus: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<BatteryStatus | null>;
+    };
+    idle: {
+        opt: IdleOptions;
+        returnType: IdleSignal;
+    };
+    focusWithin: {
+        opt: {
+            debugName?: string;
+            target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
+        };
+        returnType: Signal<boolean>;
+    };
 };
 /**
  * Creates a sensor signal that the elements visiblity within the viewport
@@ -1444,14 +1838,106 @@ declare function sensor(type: 'windowSize', options?: SensorTypedOptions['window
  * @example const pageScroll = sensor('scrollPosition', { throttle: 150 });
  */
 declare function sensor(type: 'scrollPosition', options?: SensorTypedOptions['scrollPosition']['opt']): ScrollPositionSignal;
+/**
+ * Creates a sensor signal exposing the device's current geolocation position.
+ * @see {geolocation}
+ */
+declare function sensor(type: 'geolocation', options?: SensorTypedOptions['geolocation']['opt']): GeolocationSignal;
+/**
+ * Creates a sensor signal mirroring the system clipboard contents.
+ * @see {clipboard}
+ */
+declare function sensor(type: 'clipboard', options?: SensorTypedOptions['clipboard']['opt']): ClipboardSignal;
+/**
+ * Creates a sensor signal tracking the screen orientation.
+ * @see {orientation}
+ */
+declare function sensor(type: 'orientation', options?: SensorTypedOptions['orientation']['opt']): Signal<ScreenOrientation>;
+/**
+ * Creates a sensor signal tracking the system battery status.
+ * @see {batteryStatus}
+ */
+declare function sensor(type: 'batteryStatus', options?: SensorTypedOptions['batteryStatus']['opt']): Signal<BatteryStatus | null>;
+/**
+ * Creates a sensor signal that flips to `true` after a window of user inactivity.
+ * @see {idle}
+ */
+declare function sensor(type: 'idle', options?: SensorTypedOptions['idle']['opt']): IdleSignal;
+/**
+ * Creates a sensor signal tracking whether focus is within a target subtree.
+ * @see {focusWithin}
+ */
+declare function sensor(type: 'focusWithin', options?: SensorTypedOptions['focusWithin']['opt']): Signal<boolean>;
 type SensorsOptions<TKey extends keyof SensorTypedOptions> = {
     [K in TKey]: SensorTypedOptions[K]['opt'];
 };
 type Sensors<TKey extends keyof SensorTypedOptions> = {
     [K in TKey]: SensorTypedOptions[K]['returnType'];
 };
+/**
+ * Bulk sensor factory — creates several sensor signals at once and returns
+ * them keyed by sensor type. Convenient when a single consumer needs to react
+ * to multiple browser signals; for a single sensor prefer {@link sensor}
+ * directly.
+ *
+ * @typeParam TType The union of sensor keys being requested.
+ * @param track Array of sensor type keys to create.
+ * @param opt Optional per-sensor options keyed by sensor type.
+ * @returns A record `{ [key]: <SensorReturnType> }` for each requested key.
+ *
+ * @example
+ * ```ts
+ * const { windowSize, networkStatus } = sensors(
+ *   ['windowSize', 'networkStatus'],
+ *   { windowSize: { throttle: 200 } },
+ * );
+ *
+ * effect(() => console.log(windowSize(), networkStatus()));
+ * ```
+ */
 declare function sensors<const TType extends keyof SensorTypedOptions>(track: TType[], opt?: SensorsOptions<TType>): Sensors<TType>;
 
+/**
+ * Options for {@link signalFromEvent}. Extends the native
+ * `AddEventListenerOptions` so callers can opt into `capture`, `passive`, etc.
+ */
+type SignalFromEventOptions = AddEventListenerOptions & {
+    /** Optional debug name for the produced signal. */
+    debugName?: string;
+    /** Override the DestroyRef used to remove the listener on teardown. */
+    destroyRef?: DestroyRef;
+    /** Override the Injector used to inject dependencies. */
+    injector?: Injector;
+};
+type EventTargetLike = EventTarget | ElementRef<EventTarget>;
+type ResolvableTarget = EventTargetLike | Signal<EventTargetLike | null>;
+/**
+ * Creates a read-only signal that emits the latest event dispatched on a
+ * target. The target can be a static `EventTarget`, an `ElementRef`, or a
+ * `Signal` that resolves to one (or `null` to detach).
+ *
+ * SSR-safe: on the server the signal returns the provided `initial` value and
+ * no listener is registered.
+ *
+ * @example
+ * ```ts
+ * const click = signalFromEvent(document, 'click', null);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a projection — store just the coordinates.
+ * const point = signalFromEvent<MouseEvent, { x: number; y: number }>(
+ *   document,
+ *   'mousemove',
+ *   { x: 0, y: 0 },
+ *   (e) => ({ x: e.clientX, y: e.clientY }),
+ * );
+ * ```
+ */
+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>;
+
 type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp;
 type Key = string | number;
 type AnyRecord = Record<Key, any>;
@@ -1646,47 +2132,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>;
 
-type SyncSignalOptions = {
+type LegacySyncSignalOptions = {
     id?: string;
 };
+type SyncSignalOptions = {
+    id: string;
+};
 /**
- * Synchronizes a WritableSignal across browser tabs using BroadcastChannel API.
- *
- * Creates a shared signal that automatically syncs its value between all tabs
- * of the same application. When the signal is updated in one tab, all other
- * tabs will receive the new value automatically.
- *
- * @template T - The type of the WritableSignal
- * @param sig - The WritableSignal to synchronize across tabs
- * @param opt - Optional configuration object
- * @param opt.id - Explicit channel ID for synchronization. If not provided,
- *                 a deterministic ID is generated based on the call site.
- *                 Use explicit IDs in production for reliability.
- *
- * @returns The same WritableSignal instance, now synchronized across tabs
- *
+ * @example tabSync(signal('dark), {id: 'theme})
+ */
+declare function tabSync<T extends WritableSignal<any>>(sig: T, opt: SyncSignalOptions | string): T;
+/**
+ * @deprecated Use `tabSync` with `SyncSignalOptions` instead and pass the options as the second argument
  * @throws {Error} When deterministic ID generation fails and no explicit ID is provided
- *
- * @example
- * ```typescript
- * // Basic usage - auto-generates channel ID from call site
- * const theme = tabSync(signal('dark'));
- *
- * // With explicit ID (recommended for production)
- * const userPrefs = tabSync(signal({ lang: 'en' }), { id: 'user-preferences' });
- *
- * // Changes in one tab will sync to all other tabs
- * theme.set('light'); // All tabs will update to 'light'
- * ```
- *
- * @remarks
- * - Only works in browser environments (returns original signal on server)
- * - Uses a single BroadcastChannel for all synchronized signals
- * - Automatically cleans up listeners when the injection context is destroyed
- * - Initial signal value after sync setup is not broadcasted to prevent loops
- *
  */
-declare function tabSync<T extends WritableSignal<any>>(sig: T, opt?: SyncSignalOptions): T;
+declare function tabSync<T extends WritableSignal<any>>(sig: T, opt?: LegacySyncSignalOptions): T;
 
 /**
  * Options for creating a throttled writable signal.
@@ -1707,6 +2167,18 @@ type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
      * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)
      */
     destroyRef?: DestroyRef;
+    /**
+     * If `true`, the throttled signal emits the first value immediately when a
+     * burst starts, then enforces the cooldown window before the next emission.
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * 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).
+     * @default true
+     */
+    trailing?: boolean;
 };
 /**
  * A specialized `WritableSignal` whose publicly readable value updates are throttled.
@@ -1947,7 +2419,7 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  * console.log('Can undo:', name.canUndo()); // false
  * ```
  */
-declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
+declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
-export type { Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal, WritableSignalStore };
+export { batteryStatus, chunked, clipboard, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, geolocation, idle, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, orientation, pageVisibility, pairwise, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, 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, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, PipeableSignal, ScreenOrientation, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal, WritableSignalStore };