@angular-helpers/browser-web-apis 21.6.0 → 21.9.0

package/types/angular-helpers-browser-web-apis.d.ts

@@ -3,145 +3,6 @@ import * as i0 from '@angular/core';
 import { DestroyRef, ElementRef, Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
 import { CanActivateFn } from '@angular/router';
 
-/**
- * Base class for all Browser Web API services.
- * Provides common functionality for:
- * - Platform detection (browser vs server)
- * - Support assertion via Template Method
- * - Error creation with cause chaining
- * - Structured logging via injectable BROWSER_API_LOGGER token
- * - Lifecycle management with destroyRef
- *
- * Services that also need permission querying should extend
- * `PermissionAwareBrowserApiBaseService` instead.
- */
-declare abstract class BrowserApiBaseService {
-    protected destroyRef: DestroyRef;
-    protected platformId: Object;
-    private readonly logger;
-    /**
-     * Abstract method that must be implemented by child services.
-     * Returns the API name used in log messages and error strings.
-     */
-    protected abstract getApiName(): string;
-    /**
-     * Check if running in browser environment using Angular's platform detection.
-     */
-    protected isBrowserEnvironment(): boolean;
-    /**
-     * Check if running in server environment using Angular's platform detection.
-     */
-    protected isServerEnvironment(): boolean;
-    /**
-     * Template Method: asserts the service can run in the current environment.
-     * Subclasses must call super.ensureSupported() and then add their own API check.
-     */
-    protected ensureSupported(): void;
-    /**
-     * Create an error with proper cause chaining.
-     */
-    protected createError(message: string, cause?: unknown): Error;
-    /**
-     * Log an error through the injected BROWSER_API_LOGGER (default: console).
-     */
-    protected logError(message: string, error?: unknown): void;
-    /**
-     * Log a warning through the injected BROWSER_API_LOGGER (default: console).
-     */
-    protected logWarn(message: string): void;
-    /**
-     * Log an informational message through the injected BROWSER_API_LOGGER (default: console).
-     */
-    protected logInfo(message: string): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<BrowserApiBaseService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<BrowserApiBaseService>;
-}
-
-type PermissionNameExt = PermissionName | 'clipboard-read' | 'clipboard-write';
-interface PermissionRequest {
-    name: PermissionNameExt;
-    state: PermissionState;
-}
-interface BrowserPermissions {
-    query(descriptor: PermissionDescriptor): Promise<PermissionStatus>;
-    isSupported(): boolean;
-}
-
-declare class PermissionsService extends BrowserApiBaseService implements BrowserPermissions {
-    protected getApiName(): string;
-    query(descriptor: PermissionDescriptor): Promise<PermissionStatus>;
-    isSupported(): boolean;
-    static ɵfac: i0.ɵɵFactoryDeclaration<PermissionsService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<PermissionsService>;
-}
-
-declare class CameraService extends BrowserApiBaseService {
-    private currentStream;
-    protected getApiName(): string;
-    protected ensureSupported(): void;
-    startCamera(constraints?: MediaStreamConstraints): Promise<MediaStream>;
-    stopCamera(): void;
-    switchCamera(deviceId: string, constraints?: MediaStreamConstraints): Promise<MediaStream>;
-    getCameraCapabilities(deviceId: string): Promise<MediaTrackCapabilities | null>;
-    getCurrentStream(): MediaStream | null;
-    isStreaming(): boolean;
-    getVideoInputDevices(): Promise<MediaDeviceInfo[]>;
-    getNativeMediaDevices(): MediaDevices;
-    static ɵfac: i0.ɵɵFactoryDeclaration<CameraService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<CameraService>;
-}
-
-declare class GeolocationService extends BrowserApiBaseService {
-    protected getApiName(): string;
-    protected ensureSupported(): void;
-    getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
-    watchPosition(options?: PositionOptions): Observable<GeolocationPosition>;
-    clearWatch(watchId: number): void;
-    getNativeGeolocation(): Geolocation;
-    static ɵfac: i0.ɵɵFactoryDeclaration<GeolocationService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<GeolocationService>;
-}
-
-interface DisplayMediaConstraints {
-    video?: boolean | MediaTrackConstraints;
-    audio?: boolean | MediaTrackConstraints;
-}
-declare class MediaDevicesService extends BrowserApiBaseService {
-    protected getApiName(): string;
-    protected ensureSupported(): void;
-    getDevices(): Promise<MediaDeviceInfo[]>;
-    getUserMedia(constraints?: MediaStreamConstraints): Promise<MediaStream>;
-    getDisplayMedia(constraints?: DisplayMediaConstraints): Promise<MediaStream>;
-    watchDeviceChanges(): Observable<MediaDeviceInfo[]>;
-    getVideoInputDevices(): Promise<MediaDeviceInfo[]>;
-    getAudioInputDevices(): Promise<MediaDeviceInfo[]>;
-    getAudioOutputDevices(): Promise<MediaDeviceInfo[]>;
-    private getDevicesByKind;
-    private handleMediaError;
-    getNativeMediaDevices(): MediaDevices;
-    static ɵfac: i0.ɵɵFactoryDeclaration<MediaDevicesService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<MediaDevicesService>;
-}
-
-declare class NotificationService extends BrowserApiBaseService {
-    protected getApiName(): string;
-    protected ensureSupported(): void;
-    get permission(): NotificationPermission;
-    requestNotificationPermission(): Promise<NotificationPermission>;
-    showNotification(title: string, options?: NotificationOptions): Promise<Notification>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NotificationService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<NotificationService>;
-}
-
-declare class ClipboardService extends BrowserApiBaseService {
-    protected getApiName(): string;
-    protected ensureSupported(): void;
-    writeText(text: string): Promise<void>;
-    readText(): Promise<string>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ClipboardService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<ClipboardService>;
-}
-
 type BrowserCapabilityId = 'permissions' | 'geolocation' | 'clipboard' | 'notification' | 'mediaDevices' | 'camera' | 'webWorker' | 'regexSecurity' | 'webStorage' | 'webShare' | 'battery' | 'webSocket' | 'intersectionObserver' | 'resizeObserver' | 'pageVisibility' | 'broadcastChannel' | 'networkInformation' | 'screenWakeLock' | 'screenOrientation' | 'fullscreen' | 'fileSystemAccess' | 'mediaRecorder' | 'serverSentEvents' | 'vibration' | 'speechSynthesis' | 'mutationObserver' | 'performanceObserver' | 'idleDetector' | 'eyeDropper' | 'barcodeDetector' | 'webAudio' | 'gamepad' | 'webBluetooth' | 'webUsb' | 'webNfc' | 'paymentRequest' | 'credentialManagement';
 declare class BrowserCapabilityService {
     getCapabilities(): readonly [{
@@ -296,7 +157,7 @@ declare class BrowserCapabilityService {
     isSecureContext(): boolean;
     isSupported(capability: BrowserCapabilityId): boolean;
     getAllStatuses(): {
-        id: "camera" | "geolocation" | "permissions" | "clipboard" | "notification" | "mediaDevices" | "webWorker" | "regexSecurity" | "webStorage" | "webShare" | "battery" | "webSocket" | "intersectionObserver" | "resizeObserver" | "pageVisibility" | "broadcastChannel" | "networkInformation" | "screenWakeLock" | "screenOrientation" | "fullscreen" | "fileSystemAccess" | "mediaRecorder" | "serverSentEvents" | "vibration" | "speechSynthesis" | "mutationObserver" | "performanceObserver" | "idleDetector" | "eyeDropper" | "barcodeDetector" | "webAudio" | "gamepad" | "webBluetooth" | "webUsb" | "webNfc" | "paymentRequest" | "credentialManagement";
+        id: "permissions" | "geolocation" | "clipboard" | "notification" | "mediaDevices" | "camera" | "webWorker" | "regexSecurity" | "webStorage" | "webShare" | "battery" | "webSocket" | "intersectionObserver" | "resizeObserver" | "pageVisibility" | "broadcastChannel" | "networkInformation" | "screenWakeLock" | "screenOrientation" | "fullscreen" | "fileSystemAccess" | "mediaRecorder" | "serverSentEvents" | "vibration" | "speechSynthesis" | "mutationObserver" | "performanceObserver" | "idleDetector" | "eyeDropper" | "barcodeDetector" | "webAudio" | "gamepad" | "webBluetooth" | "webUsb" | "webNfc" | "paymentRequest" | "credentialManagement";
         label: "Permissions API" | "Geolocation API" | "Clipboard API" | "Notification API" | "MediaDevices API" | "Camera API" | "Web Worker API" | "Regex Security" | "Web Storage" | "Web Share" | "Battery API" | "WebSocket API" | "Intersection Observer" | "Resize Observer" | "Page Visibility API" | "Broadcast Channel API" | "Network Information API" | "Screen Wake Lock API" | "Screen Orientation API" | "Fullscreen API" | "File System Access API" | "MediaRecorder API" | "Server-Sent Events" | "Vibration API" | "Speech Synthesis API" | "Mutation Observer" | "Performance Observer" | "Idle Detection API" | "EyeDropper API" | "Barcode Detection API" | "Web Audio API" | "Gamepad API" | "Web Bluetooth API" | "WebUSB API" | "Web NFC API" | "Payment Request API" | "Credential Management API";
         supported: boolean;
         secureContext: boolean;
@@ -307,7 +168,149 @@ declare class BrowserCapabilityService {
     static ɵprov: i0.ɵɵInjectableDeclaration<BrowserCapabilityService>;
 }
 
-interface BatteryInfo {
+/**
+ * Base class for all Browser Web API services.
+ *
+ * ## Support detection contract
+ *
+ * Services follow ONE pattern (do not invent variants):
+ *
+ * - `isSupported(): boolean` — public, side-effect free, SSR-safe. Default
+ *   implementation delegates to {@link BrowserCapabilityService} when the subclass
+ *   overrides {@link getCapabilityId} (recommended).
+ * - `ensureSupported(): void` — internal Template Method. Throws when called outside
+ *   browser or when the underlying API is missing.
+ *
+ * ## Error surfacing contract
+ *
+ * - **Imperative methods** MUST call `ensureSupported()` and throw synchronously.
+ * - **Stream-returning methods** MUST guard with `isSupported()` and surface
+ *   unsupported state as `Observable.error(...)` (NOT throw inline).
+ *
+ * Services that also need permission querying should extend
+ * `PermissionAwareBrowserApiBaseService` instead.
+ */
+declare abstract class BrowserApiBaseService {
+    protected destroyRef: DestroyRef;
+    protected platformId: Object;
+    private readonly logger;
+    private readonly capabilities;
+    /** API name used in log messages and error strings. */
+    protected abstract getApiName(): string;
+    /**
+     * Optional hook for subclasses to delegate feature detection to
+     * {@link BrowserCapabilityService}. Returning a capability id removes the need to
+     * implement `isSupported()` manually and avoids drift between per-service checks
+     * and the centralized capability registry.
+     */
+    protected getCapabilityId(): BrowserCapabilityId | null;
+    /** Public, SSR-safe support check. Override only if you need extra constraints. */
+    isSupported(): boolean;
+    protected isBrowserEnvironment(): boolean;
+    protected isServerEnvironment(): boolean;
+    /**
+     * Template Method: asserts the service can run in the current environment. Subclasses
+     * that need extra checks beyond capability detection MUST call `super.ensureSupported()`
+     * first, then add their own check.
+     */
+    protected ensureSupported(): void;
+    protected createError(message: string, cause?: unknown): Error;
+    protected logError(message: string, error?: unknown): void;
+    protected logWarn(message: string): void;
+    protected logInfo(message: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BrowserApiBaseService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BrowserApiBaseService>;
+}
+
+type PermissionNameExt = PermissionName | 'clipboard-read' | 'clipboard-write';
+interface PermissionRequest {
+    name: PermissionNameExt;
+    state: PermissionState;
+}
+interface BrowserPermissions {
+    query(descriptor: PermissionDescriptor): Promise<PermissionStatus>;
+    isSupported(): boolean;
+}
+
+declare class PermissionsService extends BrowserApiBaseService implements BrowserPermissions {
+    protected getApiName(): string;
+    query(descriptor: PermissionDescriptor): Promise<PermissionStatus>;
+    protected getCapabilityId(): BrowserCapabilityId;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PermissionsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PermissionsService>;
+}
+
+declare class CameraService extends BrowserApiBaseService {
+    private currentStream;
+    protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    protected ensureSupported(): void;
+    startCamera(constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    stopCamera(): void;
+    switchCamera(deviceId: string, constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    getCameraCapabilities(deviceId: string): Promise<MediaTrackCapabilities | null>;
+    getCurrentStream(): MediaStream | null;
+    isStreaming(): boolean;
+    getVideoInputDevices(): Promise<MediaDeviceInfo[]>;
+    getNativeMediaDevices(): MediaDevices;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CameraService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CameraService>;
+}
+
+declare class GeolocationService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
+    watchPosition(options?: PositionOptions): Observable<GeolocationPosition>;
+    clearWatch(watchId: number): void;
+    getNativeGeolocation(): Geolocation;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GeolocationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<GeolocationService>;
+}
+
+interface DisplayMediaConstraints {
+    video?: boolean | MediaTrackConstraints;
+    audio?: boolean | MediaTrackConstraints;
+}
+declare class MediaDevicesService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    protected ensureSupported(): void;
+    getDevices(): Promise<MediaDeviceInfo[]>;
+    getUserMedia(constraints?: MediaStreamConstraints): Promise<MediaStream>;
+    getDisplayMedia(constraints?: DisplayMediaConstraints): Promise<MediaStream>;
+    watchDeviceChanges(): Observable<MediaDeviceInfo[]>;
+    getVideoInputDevices(): Promise<MediaDeviceInfo[]>;
+    getAudioInputDevices(): Promise<MediaDeviceInfo[]>;
+    getAudioOutputDevices(): Promise<MediaDeviceInfo[]>;
+    private getDevicesByKind;
+    private handleMediaError;
+    getNativeMediaDevices(): MediaDevices;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MediaDevicesService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MediaDevicesService>;
+}
+
+declare class NotificationService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    get permission(): NotificationPermission;
+    requestNotificationPermission(): Promise<NotificationPermission>;
+    showNotification(title: string, options?: NotificationOptions): Promise<Notification>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NotificationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NotificationService>;
+}
+
+declare class ClipboardService extends BrowserApiBaseService {
+    protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    protected ensureSupported(): void;
+    writeText(text: string): Promise<void>;
+    readText(): Promise<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ClipboardService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ClipboardService>;
+}
+
+interface BatteryInfo$1 {
     charging: boolean;
     chargingTime: number;
     dischargingTime: number;
@@ -336,10 +339,10 @@ declare global {
 declare class BatteryService extends BrowserApiBaseService {
     private batteryManager;
     protected getApiName(): string;
-    protected ensureSupported(): void;
-    initialize(): Promise<BatteryInfo>;
-    getBatteryInfo(): BatteryInfo;
-    watchBatteryInfo(): Observable<BatteryInfo>;
+    protected getCapabilityId(): BrowserCapabilityId;
+    initialize(): Promise<BatteryInfo$1>;
+    getBatteryInfo(): BatteryInfo$1;
+    watchBatteryInfo(): Observable<BatteryInfo$1>;
     getNativeBatteryManager(): BatteryManager;
     isCharging(): boolean;
     getLevel(): number;
@@ -355,7 +358,7 @@ interface ShareResult {
 }
 declare class WebShareService extends BrowserApiBaseService {
     protected getApiName(): string;
-    protected ensureSupported(): void;
+    protected getCapabilityId(): BrowserCapabilityId;
     share(data: ShareData): Promise<ShareResult>;
     canShare(): boolean;
     canShareFiles(): boolean;
@@ -377,53 +380,105 @@ type ErrorCallback = (error: BrowserError) => void;
  */
 type ElementInput = Element | ElementRef<Element> | Signal<Element | ElementRef<Element> | undefined>;
 
+interface BrowserApiLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string, error?: unknown): void;
+}
+declare const BROWSER_API_LOGGER: InjectionToken<BrowserApiLogger>;
+
 interface StorageOptions {
+    /** Optional prefix used to namespace keys (e.g. `app:` -> `app:userId`). */
     prefix?: string;
     serialize?: (value: StorageValue) => string;
     deserialize?: (value: string) => StorageValue;
 }
+type StorageArea = 'localStorage' | 'sessionStorage';
 interface StorageEvent {
     key: string | null;
     newValue: StorageValue | null;
     oldValue: StorageValue | null;
-    storageArea: 'localStorage' | 'sessionStorage';
+    storageArea: StorageArea;
 }
+interface StorageNamespace {
+    readonly area: StorageArea;
+    isSupported(): boolean;
+    set<T extends StorageValue>(key: string, value: T, opts?: StorageOptions): boolean;
+    get<T extends StorageValue>(key: string, defaultValue?: T | null, opts?: StorageOptions): T | null;
+    remove(key: string, opts?: StorageOptions): boolean;
+    clear(opts?: StorageOptions): boolean;
+    size(opts?: StorageOptions): number;
+    watch<T extends StorageValue>(key: string, opts?: StorageOptions): Observable<T | null>;
+    /** Direct access to the native Storage object. Throws if unsupported. */
+    native(): Storage;
+}
+
+/**
+ * Web Storage service with two namespaces (`local`, `session`) sharing one method
+ * surface. SecurityError-safe (Safari private mode, sandboxed iframes return defaults
+ * instead of throwing).
+ *
+ * Preferred usage:
+ * ```ts
+ * const storage = inject(WebStorageService);
+ * storage.local.set('user', { id: 1 });
+ * const user = storage.local.get<{ id: number }>('user');
+ * storage.local.watch<{ id: number }>('user').subscribe(console.log);
+ * ```
+ *
+ * Legacy methods (`setLocalStorage`, `getLocalStorage`, etc.) remain as deprecated
+ * wrappers for one minor cycle; removal slated for v22.
+ */
 declare class WebStorageService extends BrowserApiBaseService {
+    private readonly storageLogger;
     private storageEvents;
+    private readonly eventBus;
+    /** Local storage namespace. */
+    readonly local: StorageNamespace;
+    /** Session storage namespace. */
+    readonly session: StorageNamespace;
     constructor();
     protected getApiName(): string;
-    protected ensureSupported(): void;
-    private setupEventListeners;
-    private serializeValue;
-    private deserializeValue;
-    private getKey;
-    private emitStorageChange;
+    protected getCapabilityId(): BrowserCapabilityId;
+    /** Returns true if either local or session storage is usable. */
+    isSupported(): boolean;
+    /** Stream of every storage mutation observed in this tab or other tabs. */
+    getStorageEvents(): Observable<StorageEvent>;
+    private setupCrossTabListener;
+    private safeParse;
+    /** @deprecated Use `storage.local.set(key, value, opts)`. Removed in v22. */
     setLocalStorage<T extends StorageValue>(key: string, value: T, options?: StorageOptions): boolean;
+    /** @deprecated Use `storage.local.get(key, defaultValue, opts)`. Removed in v22. */
     getLocalStorage<T extends StorageValue>(key: string, defaultValue?: T | null, options?: StorageOptions): T | null;
+    /** @deprecated Use `storage.local.remove(key, opts)`. Removed in v22. */
     removeLocalStorage(key: string, options?: StorageOptions): boolean;
+    /** @deprecated Use `storage.local.clear(opts)`. Removed in v22. */
     clearLocalStorage(options?: StorageOptions): boolean;
+    /** @deprecated Use `storage.session.set(key, value, opts)`. Removed in v22. */
     setSessionStorage<T extends StorageValue>(key: string, value: T, options?: StorageOptions): boolean;
+    /** @deprecated Use `storage.session.get(key, defaultValue, opts)`. Removed in v22. */
     getSessionStorage<T extends StorageValue>(key: string, defaultValue?: T | null, options?: StorageOptions): T | null;
+    /** @deprecated Use `storage.session.remove(key, opts)`. Removed in v22. */
     removeSessionStorage(key: string, options?: StorageOptions): boolean;
+    /** @deprecated Use `storage.session.clear(opts)`. Removed in v22. */
     clearSessionStorage(options?: StorageOptions): boolean;
+    /** @deprecated Use `storage.local.size(opts)`. Removed in v22. */
     getLocalStorageSize(options?: StorageOptions): number;
+    /** @deprecated Use `storage.session.size(opts)`. Removed in v22. */
     getSessionStorageSize(options?: StorageOptions): number;
-    getStorageEvents(): Observable<StorageEvent>;
+    /** @deprecated Use `storage.local.watch<T>(key, opts)`. Removed in v22. */
     watchLocalStorage<T extends StorageValue>(key: string, options?: StorageOptions): Observable<T | null>;
+    /** @deprecated Use `storage.session.watch<T>(key, opts)`. Removed in v22. */
     watchSessionStorage<T extends StorageValue>(key: string, options?: StorageOptions): Observable<T | null>;
+    /** @deprecated Use `storage.local.native()`. Removed in v22. */
     getNativeLocalStorage(): Storage;
+    /** @deprecated Use `storage.session.native()`. Removed in v22. */
     getNativeSessionStorage(): Storage;
+    private warnLegacyOnce;
     static ɵfac: i0.ɵɵFactoryDeclaration<WebStorageService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<WebStorageService>;
 }
 
-interface BrowserApiLogger {
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string, error?: unknown): void;
-}
-declare const BROWSER_API_LOGGER: InjectionToken<BrowserApiLogger>;
-
 /**
  * Configuration for a single WebSocket connection.
  */
@@ -559,7 +614,7 @@ declare class WebSocketService extends BrowserApiBaseService {
     /** Legacy single-connection holder used by deprecated `connect()`/`send()` API. */
     private legacyClient;
     protected getApiName(): string;
-    protected ensureSupported(): void;
+    protected getCapabilityId(): BrowserCapabilityId;
     /**
      * Create a new WebSocket client. The client owns one connection and is the recommended
      * surface for all interactions (status signal, request/response, reconnect, etc.).
@@ -603,6 +658,8 @@ interface WorkerMessage<T = unknown> {
     type: string;
     data: T;
     timestamp: number;
+    /** Set on responses to correlate with a `request()` call. */
+    correlationId?: string;
 }
 interface WorkerStatus {
     initialized: boolean;
@@ -611,32 +668,77 @@ interface WorkerStatus {
     messageCount: number;
 }
 interface WorkerTask<T = unknown> {
-    id: string;
+    id?: string;
     type: string;
     data: T;
     transferable?: Transferable[];
 }
+interface WorkerRequestOptions {
+    /** Timeout in milliseconds. Defaults to `30_000`. */
+    timeout?: number;
+    /** Transferable list forwarded to `postMessage`. */
+    transferable?: Transferable[];
+}
+/**
+ * Service for creating and managing Web Workers with first-class support for
+ * request/response over `postMessage` (id correlation, timeout, transferables).
+ *
+ * Status is exposed both as a `Signal<WorkerStatus>` (preferred via
+ * {@link getStatusSignal}) and as an `Observable<WorkerStatus>` for backward
+ * compatibility ({@link createWorker}, {@link getStatus}).
+ *
+ * The service registers a single `DestroyRef.onDestroy` in its constructor that
+ * terminates every registered worker; per-worker handlers do not register their
+ * own cleanup callbacks (avoids accumulating callbacks per `setupWorker` call,
+ * a previous leak source).
+ */
 declare class WebWorkerService extends BrowserApiBaseService {
-    private workers;
-    private workerStatuses;
-    private workerMessages;
-    private currentWorkerStatuses;
+    private readonly workerLogger;
+    private readonly entries;
     private readonly _cleanup;
     protected getApiName(): string;
-    protected ensureSupported(): void;
+    protected getCapabilityId(): BrowserCapabilityId;
+    /**
+     * Create a worker. Idempotent: calling twice with the same name returns the
+     * existing entry without recreating the worker.
+     *
+     * Returns an `Observable<WorkerStatus>` for backward compatibility. Prefer
+     * {@link createWorkerSignal} for new code.
+     */
     createWorker(name: string, scriptUrl: string): Observable<WorkerStatus>;
+    /**
+     * Create a worker (signal-first). Returns the status signal; status is also
+     * accessible later via {@link getStatusSignal}.
+     */
+    createWorkerSignal(name: string, scriptUrl: string): Signal<WorkerStatus>;
     terminateWorker(name: string): void;
     terminateAllWorkers(): void;
+    /** Send a fire-and-forget message. Use {@link request} when you need a reply. */
     postMessage(workerName: string, task: WorkerTask): void;
-    getMessages(workerName: string): Observable<WorkerMessage>;
+    /**
+     * Send a message and await a correlated response. The worker MUST send back a
+     * message containing `correlationId` matching the request id.
+     *
+     * ```ts
+     * const result = await ws.request<{ ok: boolean }>('worker', 'compute', { n: 1 });
+     * ```
+     */
+    request<TRes = unknown, TReq = unknown>(workerName: string, type: string, data: TReq, opts?: WorkerRequestOptions): Promise<TRes>;
+    getMessages<T = unknown>(workerName: string): Observable<WorkerMessage<T>>;
+    getMessagesByType<T = unknown>(workerName: string, type: string): Observable<WorkerMessage<T>>;
+    /** @deprecated Use {@link getStatusSignal}. Kept as Observable for backward compat. */
     getStatus(workerName: string): Observable<WorkerStatus>;
+    getStatusSignal(workerName: string): Signal<WorkerStatus>;
     getCurrentStatus(workerName: string): WorkerStatus | undefined;
     getAllStatuses(): Map<string, WorkerStatus>;
     isWorkerRunning(workerName: string): boolean;
-    private setupWorker;
-    private updateWorkerStatus;
     getNativeWorker(name: string): Worker | undefined;
     getAllWorkers(): Map<string, Worker>;
+    private attachHandlers;
+    private rejectPending;
+    private bumpMessageCount;
+    private ensureEntry;
+    private generateId;
     static ɵfac: i0.ɵɵFactoryDeclaration<WebWorkerService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<WebWorkerService>;
 }
@@ -648,7 +750,7 @@ interface IntersectionObserverOptions {
 }
 declare class IntersectionObserverService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     observe(element: Element, options?: IntersectionObserverOptions): Observable<IntersectionObserverEntry[]>;
     observeVisibility(element: Element, options?: IntersectionObserverOptions): Observable<boolean>;
     static ɵfac: i0.ɵɵFactoryDeclaration<IntersectionObserverService, never>;
@@ -666,7 +768,7 @@ interface ElementSize {
 }
 declare class ResizeObserverService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     observe(element: Element, options?: ResizeObserverOptions): Observable<ResizeObserverEntry[]>;
     observeSize(element: Element, options?: ResizeObserverOptions): Observable<ElementSize>;
     static ɵfac: i0.ɵɵFactoryDeclaration<ResizeObserverService, never>;
@@ -676,7 +778,7 @@ declare class ResizeObserverService extends BrowserApiBaseService {
 type VisibilityState = 'visible' | 'hidden' | 'prerender';
 declare class PageVisibilityService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     get isHidden(): boolean;
     get visibilityState(): VisibilityState;
     watch(): Observable<VisibilityState>;
@@ -723,7 +825,7 @@ declare abstract class ConnectionRegistryBaseService<T> extends BrowserApiBaseSe
 declare class BroadcastChannelService extends ConnectionRegistryBaseService<BroadcastChannel> {
     protected getApiName(): string;
     protected closeNativeConnection(channel: BroadcastChannel): void;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     private ensureBroadcastChannelSupported;
     open<T = unknown>(name: string): Observable<T>;
     post<T = unknown>(name: string, data: T): void;
@@ -747,7 +849,7 @@ interface NetworkInformation {
 }
 declare class NetworkInformationService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     getSnapshot(): NetworkInformation;
     watch(): Observable<NetworkInformation>;
     get isOnline(): boolean;
@@ -764,7 +866,7 @@ interface WakeLockStatus {
 declare class ScreenWakeLockService extends BrowserApiBaseService {
     private sentinel;
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     get isActive(): boolean;
     request(type?: WakeLockType): Promise<WakeLockStatus>;
     release(): Promise<void>;
@@ -781,7 +883,7 @@ interface OrientationInfo {
 }
 declare class ScreenOrientationService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     getSnapshot(): OrientationInfo;
     get isPortrait(): boolean;
     get isLandscape(): boolean;
@@ -794,6 +896,8 @@ declare class ScreenOrientationService extends BrowserApiBaseService {
 
 declare class FullscreenService extends BrowserApiBaseService {
     protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    /** Override to also check the *enabled* flag (browser may have disabled fullscreen). */
     isSupported(): boolean;
     get isFullscreen(): boolean;
     get fullscreenElement(): Element | null;
@@ -823,6 +927,8 @@ interface FileSaveOptions {
 }
 declare class FileSystemAccessService extends BrowserApiBaseService {
     protected getApiName(): string;
+    protected getCapabilityId(): BrowserCapabilityId;
+    /** Override to also assert secure context (required by the spec). */
     isSupported(): boolean;
     private get win();
     protected ensureSupported(): void;
@@ -860,7 +966,7 @@ declare class MediaRecorderService extends BrowserApiBaseService {
     private readonly dataSubject;
     private readonly stateSubject;
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     get state(): RecordingState;
     static isTypeSupported(mimeType: string): boolean;
     watchState(): Observable<RecordingState>;
@@ -888,7 +994,7 @@ interface SSEConfig {
 declare class ServerSentEventsService extends ConnectionRegistryBaseService<EventSource> {
     protected getApiName(): string;
     protected closeNativeConnection(source: EventSource): void;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     private ensureSSESupported;
     connect<T = unknown>(url: string, config?: SSEConfig): Observable<SSEMessage<T>>;
     disconnect(url: string): void;
@@ -909,7 +1015,7 @@ interface VibrationPreset {
 declare class VibrationService extends BrowserApiBaseService {
     protected getApiName(): string;
     readonly presets: VibrationPreset;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     vibrate(pattern?: VibrationPattern): boolean;
     success(): boolean;
     error(): boolean;
@@ -930,7 +1036,7 @@ interface SpeechOptions {
 }
 declare class SpeechSynthesisService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     private ensureSpeechSynthesisSupported;
     get state(): SpeechState;
     get isPending(): boolean;
@@ -956,7 +1062,7 @@ interface MutationObserverOptions {
 
 declare class MutationObserverService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     observe(target: Node, options?: MutationObserverOptions): Observable<MutationRecord[]>;
     static ɵfac: i0.ɵɵFactoryDeclaration<MutationObserverService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MutationObserverService>;
@@ -971,7 +1077,7 @@ interface PerformanceObserverConfig {
 
 declare class PerformanceObserverService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     observe(config: PerformanceObserverConfig): Observable<PerformanceEntryList>;
     observeByType(type: PerformanceEntryType, buffered?: boolean): Observable<PerformanceEntryList>;
     getSupportedEntryTypes(): PerformanceEntryType[];
@@ -987,7 +1093,7 @@ interface AudioAnalyserData {
 declare class WebAudioService extends BrowserApiBaseService {
     protected getApiName(): string;
     private context;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     getContext(): AudioContext;
     resume(): Promise<void>;
     close(): Promise<void>;
@@ -1016,7 +1122,7 @@ interface GamepadState {
 
 declare class GamepadService extends BrowserApiBaseService {
     protected getApiName(): string;
-    isSupported(): boolean;
+    protected getCapabilityId(): BrowserCapabilityId;
     getSnapshot(index: number): GamepadState | null;
     getConnectedGamepads(): GamepadState[];
     watchConnections(): Observable<{
@@ -1101,7 +1207,7 @@ interface GeolocationCoordinates {
     heading: number | null;
     speed: number | null;
 }
-interface GeolocationOptions {
+interface GeolocationOptions$1 {
     enableHighAccuracy?: boolean;
     timeout?: number;
     maximumAge?: number;
@@ -1113,7 +1219,7 @@ interface GeolocationError {
     POSITION_UNAVAILABLE: number;
     TIMEOUT: number;
 }
-interface GeolocationWatchOptions extends GeolocationOptions {
+interface GeolocationWatchOptions extends GeolocationOptions$1 {
     maximumAge?: number;
 }
 
@@ -1185,6 +1291,62 @@ interface GamepadRef {
 }
 declare function injectGamepad(index: number, intervalMs?: number): GamepadRef;
 
+interface ClipboardRef {
+    /** Last text successfully read from the clipboard, or `null`. */
+    readonly text: Signal<string | null>;
+    /** Last error message from a read/write attempt, or `null`. */
+    readonly error: Signal<string | null>;
+    /** True when a read/write is in flight. */
+    readonly busy: Signal<boolean>;
+    /** True when the Clipboard API is available in the current environment. */
+    readonly isSupported: Signal<boolean>;
+    writeText(value: string): Promise<boolean>;
+    readText(): Promise<string | null>;
+}
+declare function injectClipboard(): ClipboardRef;
+
+interface GeolocationOptions extends PositionOptions {
+    /** Start watching immediately. Defaults to `false`. */
+    watch?: boolean;
+}
+interface GeolocationRef {
+    readonly position: Signal<GeolocationPosition | null>;
+    readonly error: Signal<GeolocationPositionError | null>;
+    readonly watching: Signal<boolean>;
+    readonly isSupported: Signal<boolean>;
+    /** Start watching position. Idempotent — safe to call when already watching. */
+    watch(opts?: PositionOptions): void;
+    /** Stop watching. Idempotent. */
+    stop(): void;
+    /** One-shot read of the current position. */
+    getCurrent(opts?: PositionOptions): Promise<GeolocationPosition>;
+}
+declare function injectGeolocation(opts?: GeolocationOptions): GeolocationRef;
+
+interface BatteryInfo {
+    charging: boolean;
+    level: number;
+    chargingTime: number;
+    dischargingTime: number;
+}
+interface BatteryRef {
+    readonly info: Signal<BatteryInfo | null>;
+    readonly error: Signal<string | null>;
+    readonly isSupported: Signal<boolean>;
+    /** Force a one-shot refresh of the battery snapshot. */
+    refresh(): Promise<void>;
+}
+declare function injectBattery(): BatteryRef;
+
+interface WakeLockRef {
+    readonly active: Signal<boolean>;
+    readonly error: Signal<string | null>;
+    readonly isSupported: Signal<boolean>;
+    request(): Promise<boolean>;
+    release(): Promise<void>;
+}
+declare function injectWakeLock(): WakeLockRef;
+
 declare class BrowserSupportUtil {
     static isSupported(feature: string): boolean;
     static getUnsupportedFeatures(): string[];
@@ -1305,5 +1467,5 @@ declare function provideBrowserWebApis(config?: BrowserWebApisConfig): Environme
 
 declare const version = "0.1.0";
 
-export { BROWSER_API_LOGGER, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, ConnectionRegistryBaseService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, VibrationService, WebAudioService, WebShareService, WebSocketClient, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectGamepad, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, permissionGuard, provideBattery, provideBroadcastChannel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideVibration, provideWebAudio, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version };
-export type { AudioAnalyserData, AudioContextState, BatteryInfo, BatteryManager, BrowserApiLogger, BrowserCapabilityId, BrowserError, BrowserPermissions, BrowserWebApisConfig, CameraCapabilities, CameraInfo, ConnectionType, EffectiveConnectionType, ElementInput, ElementSize, ErrorCallback, EventHandler, FileOpenOptions, FileSaveOptions, GamepadRef, GamepadState, GeolocationCoordinates, GeolocationError, GeolocationOptions, GeolocationPosition$1 as GeolocationPosition, GeolocationWatchOptions, IntersectionObserverOptions, IntersectionRef, MediaDevice, MediaDeviceKind, MediaDevicesInfo, MediaStreamConstraints$1 as MediaStreamConstraints, MediaTrackConstraints$1 as MediaTrackConstraints, MutationObserverOptions, MutationRef, NetworkInformation, NetworkInformationRef, OrientationInfo, OrientationLockType, OrientationType, PageVisibilityRef, PerformanceEntryType, PerformanceObserverConfig, PerformanceObserverRef, PermissionNameExt, PermissionRequest, RecordingOptions, RecordingResult, RecordingState, ResizeObserverOptions, ResizeRef, SSEConfig, SSEConnectionState, SSEMessage, ScreenOrientationRef, SpeechOptions, SpeechState, StorageEvent, StorageOptions, StorageValue, VibrationPattern, VibrationPreset, VisibilityState, WakeLockStatus, WakeLockType, WebSocketClientConfig, WebSocketConfig, WebSocketMessage, WebSocketRequestOptions, WebSocketState, WebSocketStatus, WebSocketStatusV2, WorkerMessage, WorkerStatus, WorkerTask };
+export { BROWSER_API_LOGGER, BatteryService, BroadcastChannelService, BrowserApiBaseService, BrowserCapabilityService, BrowserSupportUtil, CameraService, ClipboardService, ConnectionRegistryBaseService, FileSystemAccessService, FullscreenService, GamepadService, GeolocationService, IntersectionObserverService, MediaDevicesService, MediaRecorderService, MutationObserverService, NetworkInformationService, NotificationService, PageVisibilityService, PerformanceObserverService, PermissionsService, ResizeObserverService, ScreenOrientationService, ScreenWakeLockService, ServerSentEventsService, SpeechSynthesisService, VibrationService, WebAudioService, WebShareService, WebSocketClient, WebSocketService, WebStorageService, WebWorkerService, permissionGuard as createPermissionGuard, defaultBrowserWebApisConfig, injectBattery, injectClipboard, injectGamepad, injectGeolocation, injectIntersectionObserver, injectMutationObserver, injectNetworkInformation, injectPageVisibility, injectPerformanceObserver, injectResizeObserver, injectScreenOrientation, injectWakeLock, permissionGuard, provideBattery, provideBroadcastChannel, provideBrowserWebApis, provideCamera, provideClipboard, provideCommunicationApis, provideFileSystemAccess, provideFullscreen, provideGamepad, provideGeolocation, provideIntersectionObserver, provideLocationApis, provideMediaApis, provideMediaDevices, provideMediaRecorder, provideMutationObserver, provideNetworkInformation, provideNotifications, providePageVisibility, providePerformanceObserver, providePermissions, provideResizeObserver, provideScreenOrientation, provideScreenWakeLock, provideServerSentEvents, provideSpeechSynthesis, provideStorageApis, provideVibration, provideWebAudio, provideWebShare, provideWebSocket, provideWebStorage, provideWebWorker, version };
+export type { AudioAnalyserData, AudioContextState, BatteryInfo, BatteryManager, BatteryRef, BrowserApiLogger, BrowserCapabilityId, BrowserError, BrowserPermissions, BrowserWebApisConfig, CameraCapabilities, CameraInfo, ClipboardRef, ConnectionType, EffectiveConnectionType, ElementInput, ElementSize, ErrorCallback, EventHandler, FileOpenOptions, FileSaveOptions, GamepadRef, GamepadState, GeolocationCoordinates, GeolocationError, GeolocationOptions, GeolocationPosition$1 as GeolocationPosition, GeolocationRef, GeolocationWatchOptions, IntersectionObserverOptions, IntersectionRef, MediaDevice, MediaDeviceKind, MediaDevicesInfo, MediaStreamConstraints$1 as MediaStreamConstraints, MediaTrackConstraints$1 as MediaTrackConstraints, MutationObserverOptions, MutationRef, NetworkInformation, NetworkInformationRef, OrientationInfo, OrientationLockType, OrientationType, PageVisibilityRef, PerformanceEntryType, PerformanceObserverConfig, PerformanceObserverRef, PermissionNameExt, PermissionRequest, RecordingOptions, RecordingResult, RecordingState, ResizeObserverOptions, ResizeRef, SSEConfig, SSEConnectionState, SSEMessage, ScreenOrientationRef, SpeechOptions, SpeechState, StorageEvent, StorageNamespace, StorageOptions, StorageValue, VibrationPattern, VibrationPreset, VisibilityState, WakeLockRef, WakeLockStatus, WakeLockType, WebSocketClientConfig, WebSocketConfig, WebSocketMessage, WebSocketRequestOptions, WebSocketState, WebSocketStatus, WebSocketStatusV2, WorkerMessage, WorkerRequestOptions, WorkerStatus, WorkerTask };