@mmstack/primitives 19.4.0 → 19.4.2

package/index.d.ts

@@ -2,7 +2,7 @@ export * from './lib/chunked';
 export * from './lib/concurrent';
 export * from './lib/debounced';
 export * from './lib/derived';
-export { nestedEffect } from './lib/effect';
+export { nestedEffect, type Frame } from './lib/effect';
 export * from './lib/keep-previous';
 export * from './lib/mappers';
 export * from './lib/mutable';
@@ -11,7 +11,7 @@ export * from './lib/pooled';
 export * from './lib/sensors';
 export * from './lib/store/public_api';
 export * from './lib/stored';
-export { tabSync } from './lib/tabSync';
+export { tabSync } from './lib/tab-sync';
 export * from './lib/throttled';
 export * from './lib/to-writable';
 export * from './lib/until';

package/lib/chunked.d.ts

@@ -22,7 +22,7 @@ export 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.
@@ -31,6 +31,6 @@ export 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 });
  */
 export declare function chunked<T>(source: Signal<T[]> | (() => T[]), options?: CreateChunkedOptions<T>): Signal<T[]>;

package/lib/concurrent/pausable.d.ts

@@ -46,8 +46,9 @@ export declare function pausableEffect(effectFn: (registerCleanup: EffectCleanup
 /**
  * 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

package/lib/concurrent/start-transition.d.ts

@@ -16,5 +16,10 @@ export 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.
  */
 export declare function injectStartTransition(): (fn: () => void) => TransitionRef;

package/lib/concurrent/transaction.d.ts

@@ -32,5 +32,10 @@ export 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`.
  */
 export declare function injectStartTransaction(): (fn: () => void) => TransactionRef;

package/lib/effect/index.d.ts

@@ -1 +1,2 @@
+export type { Frame } from './frame-stack';
 export * from './nested-effect';

package/lib/get-signal-equality.d.ts

@@ -1,5 +1,5 @@
 import { type Signal, type ValueEqualityFn } from '@angular/core';
 /**
- * @interal
+ * @internal
  */
 export declare function getSignalEquality<T>(sig: Signal<T>): ValueEqualityFn<T>;

package/lib/mutable.d.ts

@@ -92,4 +92,4 @@ export declare function mutable<T>(initial: T, opt?: CreateSignalOptions<T>): Mu
  *   myMutableSignal.mutate(x => x + 1); // This is safe.
  * }
  */
-export declare function isMutable<T = any>(value: WritableSignal<T>): value is MutableSignal<T>;
+export declare function isMutable<T = unknown>(value: WritableSignal<T>): value is MutableSignal<T>;

package/lib/pipeable/{pipeble.d.ts → pipeable.d.ts}

@@ -10,7 +10,7 @@ import type { PipeableSignal, SignalValue } from './types';
  */
 export 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(...)`.

package/lib/pipeable/public_api.d.ts

@@ -1,3 +1,3 @@
 export * from './operators';
-export * from './pipeble';
+export * from './pipeable';
 export { type PipeableSignal } from './types';

package/lib/pipeable/types.d.ts

@@ -39,7 +39,7 @@ type SignalPipe<In> = {
  * @see {@link SignalPipe}
  * @example
  * ```ts
- * import { piped } from '@ngrx/signals';
+ * import { piped } from '@mmstack/primitives';
  *
  * const count = piped(1);
  *

package/lib/sensors/battery-status.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 export type BatteryStatus = {
     readonly level: number;
     readonly charging: boolean;
@@ -20,4 +21,4 @@ export type BatteryStatus = {
  * });
  * ```
  */
-export declare function batteryStatus(debugName?: string): Signal<BatteryStatus | null>;
+export declare function batteryStatus(opt?: string | SensorRunOptions): Signal<BatteryStatus | null>;

package/lib/sensors/clipboard.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 export type ClipboardSignal = Signal<string> & {
     /**
      * Writes `value` to the system clipboard. Resolves once the write completes;
@@ -19,4 +20,4 @@ export type ClipboardSignal = Signal<string> & {
  * in browsers that gate it. Errors from `navigator.clipboard.readText` are
  * swallowed silently to keep the signal value stable.
  */
-export declare function clipboard(debugName?: string): ClipboardSignal;
+export declare function clipboard(opt?: string | SensorRunOptions): ClipboardSignal;

package/lib/sensors/element-size.d.ts

@@ -1,4 +1,5 @@
 import { ElementRef, type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * Represents the size of an element.
  */
@@ -9,10 +10,7 @@ export interface ElementSize {
 /**
  * Options for configuring the `elementSize` sensor.
  */
-export type ElementSizeOptions = ResizeObserverOptions & {
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
+export type ElementSizeOptions = ResizeObserverOptions & SensorRunOptions;
 export type ElementSizeSignal = Signal<ElementSize | undefined>;
 /**
  * Creates a read-only signal that tracks the size of a target DOM element.

package/lib/sensors/element-visibility.d.ts

@@ -1,12 +1,10 @@
 import { ElementRef, type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * Options for configuring the `elementVisibility` sensor, extending
  * standard `IntersectionObserverInit` options.
  */
-export type ElementVisibilityOptions = IntersectionObserverInit & {
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
+export type ElementVisibilityOptions = IntersectionObserverInit & SensorRunOptions;
 export type ElementVisibilitySignal = Signal<IntersectionObserverEntry | undefined> & {
     readonly visible: Signal<boolean>;
 };

package/lib/sensors/focus-within.d.ts

@@ -1,4 +1,5 @@
 import { ElementRef, type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 type FocusWithinTarget = ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
 /**
  * Creates a read-only signal that tracks whether the focused element is the
@@ -17,5 +18,5 @@ type FocusWithinTarget = ElementRef<Element> | Element | Signal<ElementRef<Eleme
  * }
  * ```
  */
-export declare function focusWithin(target?: FocusWithinTarget): Signal<boolean>;
+export declare function focusWithin(target?: FocusWithinTarget, opt?: SensorRunOptions): Signal<boolean>;
 export {};

package/lib/sensors/geolocation.d.ts

@@ -1,13 +1,12 @@
 import { type Signal } from '@angular/core';
-export type GeolocationOptions = PositionOptions & {
+import { type SensorRunOptions } from './sensor-options';
+export 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;
 };
 export type GeolocationSignal = Signal<GeolocationPosition | null> & {
     readonly error: Signal<GeolocationPositionError | null>;

package/lib/sensors/idle.d.ts

@@ -1,5 +1,6 @@
 import { type Signal } from '@angular/core';
-export type IdleOptions = {
+import { type SensorRunOptions } from './sensor-options';
+export type IdleOptions = SensorRunOptions & {
     /**
      * Milliseconds of user inactivity before the signal flips to `true`.
      * @default 60_000
@@ -10,11 +11,12 @@ export type IdleOptions = {
      * @default ['mousemove','keydown','touchstart','scroll','visibilitychange']
      */
     events?: string[];
-    /** Optional debug name for the produced signal. */
-    debugName?: string;
 };
 export 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>;
 };
 /**

package/lib/sensors/index.d.ts

@@ -1,5 +1,6 @@
 export * from './battery-status';
 export * from './clipboard';
+export { type SensorRunOptions } from './sensor-options';
 export * from './element-size';
 export * from './element-visibility';
 export * from './focus-within';

package/lib/sensors/media-query.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -43,7 +44,7 @@ import { type Signal } from '@angular/core';
  * }
  * ```
  */
-export declare function mediaQuery(query: string, debugName?: string): Signal<boolean>;
+export 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.
@@ -65,7 +66,7 @@ export declare function mediaQuery(query: string, debugName?: string): Signal<bo
  * });
  * ```
  */
-export declare function prefersDarkMode(debugName?: string): Signal<boolean>;
+export 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.
@@ -91,4 +92,4 @@ export declare function prefersDarkMode(debugName?: string): Signal<boolean>;
  * });
  * ```
  */
-export declare function prefersReducedMotion(debugName?: string): Signal<boolean>;
+export declare function prefersReducedMotion(opt?: string | SensorRunOptions): Signal<boolean>;

package/lib/sensors/mouse-position.d.ts

@@ -1,4 +1,5 @@
 import { ElementRef, type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 type MousePosition = {
     x: number;
     y: number;
@@ -6,13 +7,15 @@ type MousePosition = {
 /**
  * Options for configuring the `mousePosition` sensor.
  */
-export type MousePositionOptions = {
+export 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`).
@@ -26,10 +29,6 @@ export 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

package/lib/sensors/network-status.d.ts

@@ -1,10 +1,14 @@
 import { type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * A specialized Signal that tracks network status.
  * It's a boolean signal with an attached `since` signal.
  */
 export 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>;
 };
 /**
@@ -14,7 +18,8 @@ export 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
@@ -25,4 +30,4 @@ export type NetworkStatusSignal = Signal<boolean> & {
  * });
  * ```
  */
-export declare function networkStatus(debugName?: string): NetworkStatusSignal;
+export declare function networkStatus(opt?: string | SensorRunOptions): NetworkStatusSignal;

package/lib/sensors/orientation.d.ts

@@ -1,10 +1,17 @@
 import { type Signal } from '@angular/core';
-export type ScreenOrientation = {
+import { type SensorRunOptions } from './sensor-options';
+export 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.
+ */
+export type ScreenOrientation = ScreenOrientationState;
 /**
  * Creates a read-only signal that tracks `screen.orientation`.
  *
@@ -20,4 +27,4 @@ export type ScreenOrientation = {
  * });
  * ```
  */
-export declare function orientation(debugName?: string): Signal<ScreenOrientation>;
+export declare function orientation(opt?: string | SensorRunOptions): Signal<ScreenOrientationState>;

package/lib/sensors/page-visibility.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * Creates a read-only signal that tracks the page's visibility state.
  *
@@ -7,7 +8,8 @@ import { type Signal } from '@angular/core';
  * 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'`.
  *
@@ -35,4 +37,4 @@ import { type Signal } from '@angular/core';
  * }
  * ```
  */
-export declare function pageVisibility(debugName?: string): Signal<DocumentVisibilityState>;
+export declare function pageVisibility(opt?: string | SensorRunOptions): Signal<DocumentVisibilityState>;

package/lib/sensors/scroll-position.d.ts

@@ -1,5 +1,6 @@
 import { ElementRef, // Used for SSR fallback
 type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * Represents the scroll position.
  */
@@ -12,21 +13,21 @@ export type ScrollPosition = {
 /**
  * Options for configuring the `scrollPosition` sensor.
  */
-export type ScrollPositionOptions = {
+export 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.
@@ -57,26 +58,17 @@ export 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()));
  * }
  * }
  * ```

package/lib/sensors/sensor-options.d.ts

@@ -0,0 +1,25 @@
+import { type Injector } from '@angular/core';
+/**
+ * Options shared by every sensor: an optional `debugName` for the produced signal(s) and an
+ * optional `Injector` that lifts the injection-context requirement.
+ */
+export 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;
+};
+/**
+ * @internal Run a sensor factory inside `injector` when provided, else in the ambient
+ * injection context. Keeps every sensor's escape hatch identical and in one place.
+ */
+export declare function runInSensorContext<T>(injector: Injector | undefined, fn: () => T): T;
+/**
+ * @internal Normalize the legacy positional `debugName: string` form into {@link SensorRunOptions}.
+ */
+export declare function coerceSensorOptions(opt?: string | SensorRunOptions): SensorRunOptions;

package/lib/sensors/sensor.d.ts

@@ -1,4 +1,5 @@
 import { type ElementRef, type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 import { type BatteryStatus } from './battery-status';
 import { type ClipboardSignal } from './clipboard';
 import { type ElementSizeOptions as BaseElementSizeOptions, type ElementSizeSignal } from './element-size';
@@ -7,7 +8,7 @@ import { type GeolocationOptions, type GeolocationSignal } from './geolocation';
 import { type IdleOptions, type IdleSignal } from './idle';
 import { type MousePositionOptions, type MousePositionSignal } from './mouse-position';
 import { type NetworkStatusSignal } from './network-status';
-import { type ScreenOrientation } from './orientation';
+import { type ScreenOrientationState } from './orientation';
 import { type ScrollPositionOptions, type ScrollPositionSignal } from './scroll-position';
 import { type WindowSizeOptions, type WindowSizeSignal } from './window-size';
 type SensorTypedOptions = {
@@ -28,27 +29,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: {
@@ -60,9 +53,8 @@ type SensorTypedOptions = {
         returnType: WindowSizeSignal;
     };
     mediaQuery: {
-        opt: {
+        opt: SensorRunOptions & {
             query: string;
-            debugName?: string;
         };
         returnType: Signal<boolean>;
     };
@@ -71,21 +63,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: {
@@ -93,8 +79,7 @@ type SensorTypedOptions = {
         returnType: IdleSignal;
     };
     focusWithin: {
-        opt: {
-            debugName?: string;
+        opt: SensorRunOptions & {
             target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
         };
         returnType: Signal<boolean>;
@@ -166,12 +151,12 @@ export declare function sensor(type: 'reducedMotion' | 'reduced-motion', options
 /**
  * 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)' });
  */
-export declare function sensor(type: 'mediaQuery', options?: SensorTypedOptions['mediaQuery']['opt']): Signal<boolean>;
+export 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'`.
@@ -204,7 +189,7 @@ export declare function sensor(type: 'clipboard', options?: SensorTypedOptions['
  * Creates a sensor signal tracking the screen orientation.
  * @see {orientation}
  */
-export declare function sensor(type: 'orientation', options?: SensorTypedOptions['orientation']['opt']): Signal<ScreenOrientation>;
+export declare function sensor(type: 'orientation', options?: SensorTypedOptions['orientation']['opt']): Signal<ScreenOrientationState>;
 /**
  * Creates a sensor signal tracking the system battery status.
  * @see {batteryStatus}

package/lib/sensors/window-size.d.ts

@@ -1,4 +1,5 @@
 import { type Signal } from '@angular/core';
+import { type SensorRunOptions } from './sensor-options';
 /**
  * Represents the dimensions of the window.
  */
@@ -9,13 +10,9 @@ export type WindowSize = {
     readonly height: number;
 };
 /**
- * Options for configuring the `mousePosition` sensor.
+ * Options for configuring the `windowSize` sensor.
  */
-export type WindowSizeOptions = {
-    /**
-     * Optional debug name for the internal signal.
-     */
-    debugName?: string;
+export type WindowSizeOptions = SensorRunOptions & {
     /**
      * Optional delay in milliseconds to throttle the updates.
      * @default 100