tiny-essentials 1.28.19 → 1.29.0

package/dist/v1/libs/sw/browser/TinyServiceWorker.mjs

@@ -0,0 +1,933 @@
+import { EventEmitter } from 'events';
+import { TinyPluginCore, TinyPluginLayer, TinyPlugin } from '../../plugin/TinyPlugin.mjs';
+import TinyNotificationAdapter from './TinyNotificationAdapter.mjs';
+import { createCheckDestroyed } from '../../utils/tools.mjs';
+import { PUSH_TYPE } from '../utils.mjs';
+import { requestNotificationPermission } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinyServiceWorker');
+/**
+ * The data payload contained within the message.
+ * @typedef {any} MessagePayload - A key-value map representing the message content.
+ */
+/**
+ * Represents the options object passed to an API handler registered via `onApi`.
+ * @typedef {Object} ApiHandlerOptions
+ * @property {MessagePayload} [data] - The payload received from the browser.
+ * @property {string} correlationId - The request ID.
+ */
+/**
+ * A function that processes an incoming API request coming from the Service Worker
+ * and optionally returns the response payload.
+ * @callback ApiHandlerCallback
+ * @param {ApiHandlerOptions} options - The options for the API handler, containing the request data and correlation ID.
+ * @returns {Promise<MessagePayload|undefined> | (MessagePayload|undefined)} The response payload.
+ */
+/**
+ * Represents a message exchanged between the page and the Service Worker.
+ * @typedef {Object} ServiceWorkerMessagePayload
+ * @property {string} type - The identifier for the message type.
+ * @property {MessagePayload} [data] - The actual data content of the message.
+ */
+/**
+ * Represents the non-standard `beforeinstallprompt` event used to trigger
+ * the native PWA installation flow.
+ * @typedef {Object} BeforeInstallPromptEvent
+ * @property {() => void} preventDefault - Prevents the default browser behavior.
+ * @property {Promise<{ outcome: 'accepted' | 'dismissed' }>} userChoice - A promise that resolves with the user's choice.
+ * @property {() => Promise<void>} prompt - The method to show the native installation prompt.
+ * @property {boolean} canShare - Indicates if the event can be shared.
+ */
+/**
+ * A function used to install a plugin into the engine.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {import('../../plugin/TinyPlugin.mjs').TinyPluginInstaller<TinyServiceWorker<any, any>, Layer, IdString, VersionString, Options>} SwPluginInstaller
+ */
+/**
+ * Represents a plugin instance designed to be integrated into a TinyServiceWorker.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {TinyPlugin<TinyServiceWorker<any, any>, Layer, IdString, VersionString, Options>} TinyServiceWorkerPlugin
+ */
+/**
+ * Sends a message to the service worker controller.
+ *
+ * @param {*} message - The message to be sent to the service worker.
+ * @param {Transferable[]} [transfer] - An optional array of transferable objects to transfer ownership of.
+ * @returns {void} This function does not return a value.
+ * @throws {Error} If the Service Worker is not available or not controlling the page.
+ * @throws {TypeError} If the transfer argument is provided but is not an array.
+ */
+const postMessage = (message, transfer) => {
+    if (!('serviceWorker' in navigator) || !navigator.serviceWorker.controller) {
+        throw new Error('Service Worker is not available or not controlling the page.');
+    }
+    return navigator.serviceWorker.controller.postMessage(message, transfer ?? []);
+};
+/** @typedef {import('../utils.mjs').TinyPushMessage} TinyPushMessage */
+/**
+ * Represents the object emitted for every push event received from the Service Worker.
+ * @typedef {Object} PushEventData
+ * @property {TinyPushMessage & { notificationShown: boolean }} data - The push payload merged with the notification state.
+ * @property {MessageEvent<any>} event - The original message event.
+ * @property {boolean} notificationShown - Whether the Service Worker already displayed a notification.
+ * @property {(overrides?: Partial<import('./TinyNotificationAdapter.mjs').BrowserNotificationOptions>) => Notification|null} showNotification - Helper that renders a fallback notification in the page.
+ */
+/**
+ * An event emitter that dispatches push events keyed by topic.
+ * @typedef {import('../../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<Record<string, (payload: PushEventData) => void>>} PushEventEmitter
+ */
+/**
+ * @template {string} IdWorker
+ * @template {string | URL} SwUrl
+ * Manages Service Worker registration, versioning, and messaging.
+ */
+class TinyServiceWorker extends TinyPluginCore {
+    static postMessage = postMessage;
+    static #PUSH_TYPE = PUSH_TYPE;
+    static get PUSH_TYPE() {
+        return TinyServiceWorker.#PUSH_TYPE;
+    }
+    /**
+     * Validates if an event type is a reserved name for the internal lifecycle.
+     * @param {string} type - The name of the event to validate.
+     * @throws {TypeError} If the event name is not a non-empty string.
+     * @throws {TypeError} If the event name starts with the reserved prefix 'sw:'.
+     */
+    static #validateEventType(type) {
+        if (typeof type !== 'string' || type.trim() === '') {
+            throw new TypeError('The event type must be a non-empty string.');
+        }
+        if (type.startsWith('sw:')) {
+            throw new TypeError(`The event type "${type}" is reserved for internal PWA lifecycle management and cannot be used for Service Worker messaging.`);
+        }
+    }
+    /**
+     * Validates that a value is a non-empty string usable as an event name.
+     * @param {string} type - The value to validate.
+     * @throws {TypeError} If the value is not a non-empty string.
+     */
+    static #assertEventName(type) {
+        if (typeof type !== 'string' || type.trim() === '') {
+            throw new TypeError('The event name must be a non-empty string.');
+        }
+    }
+    /**
+     * Returns a promise that resolves when the Service Worker is ready.
+     * @returns {Promise<ServiceWorkerRegistration>} A promise that resolves to the Service Worker registration.
+     */
+    static async waitForReady() {
+        return navigator.serviceWorker.ready;
+    }
+    /** @type {ServiceWorkerRegistration | null} The active Service Worker registration instance. */
+    #registration = null;
+    /** @type {IdWorker} The unique identifier for this instance. */
+    #id;
+    /** @type {SwUrl} The URL of the service worker file. */
+    #swUrl;
+    /** @type {string} The current version of the application. */
+    #version;
+    /** @type {boolean} Indicates if the service worker is fully initialized and ready. */
+    #isReady = false;
+    /** @type {boolean} Indicates if the registration process failed. */
+    #isFailed = false;
+    /** @type {((event: MessageEvent) => void) | null} The internal handler for Service Worker messages. */
+    #messageHandler = null;
+    /** @type {BeforeInstallPromptEvent | null} The deferred installation prompt event. */
+    #deferredPrompt = null;
+    /** @type {'twa' | 'standalone' | 'browser'} The current PWA display mode. */
+    #displayMode = 'browser';
+    /** @type {Map<string, {resolve: (value: any) => void, reject: (reason: Error) => void, timer: NodeJS.Timeout}>} A map of pending API requests, keyed by their correlation ID. */
+    #pendingRequests = new Map();
+    /** @type {Map<string, ApiHandlerCallback>} A map of registered API handlers, keyed by the message type. */
+    #apiHandlers = new Map();
+    /** @type {((evt: MediaQueryListEvent) => void) | null} Handler for display mode changes. */
+    #displayModeChangeHandler = null;
+    /** @type {((e: Event) => void) | null} Handler for the beforeinstallprompt event. */
+    #beforeInstallPromptHandler = null;
+    /** @type {(() => void) | null} Handler for the appinstalled event. */
+    #appInstalledHandler = null;
+    /** @type {PushEventEmitter} Emitter used to dispatch push events to subscribers. */
+    #pushEvents = new EventEmitter();
+    /** @type {boolean} Internal flag to track if the instance has been destroyed. */
+    #isDestroyed = false;
+    /**
+     * A set of event names that must be ignored when received from the Service Worker.
+     * Useful to avoid collisions with third-party Service Workers that share the same scope.
+     * @type {Set<string>}
+     */
+    #eventBlacklist = new Set();
+    /** @returns {PushEventEmitter} The emitter to receive push events. */
+    get pushEvents() {
+        return this.#pushEvents;
+    }
+    /** @returns {boolean} True if the service worker is ready. */
+    get isReady() {
+        return this.#isReady;
+    }
+    /** @returns {boolean} True if the registration process failed. */
+    get isFailed() {
+        return this.#isFailed;
+    }
+    /** @returns {boolean} True if the instance has been destroyed. */
+    get isDestroyed() {
+        return this.#isDestroyed;
+    }
+    /**
+     * Emits a warning event and logs a message when no Service Worker controller is available.
+     */
+    #noSwControllerWarn() {
+        this.emit('sw:NoSwControllerWarn');
+        this.log('warn', 'No active controller to receive message.');
+    }
+    /** @returns {boolean} True if a service worker is supported and an active controller exists. */
+    get isSwAvailable() {
+        checkDestroy(this.#isDestroyed);
+        return 'serviceWorker' in navigator && !!navigator.serviceWorker.controller;
+    }
+    /** @returns {IdWorker} The instance ID. */
+    get id() {
+        checkDestroy(this.#isDestroyed);
+        return this.#id;
+    }
+    /** @returns {SwUrl} The service worker URL. */
+    get swUrl() {
+        checkDestroy(this.#isDestroyed);
+        return this.#swUrl;
+    }
+    /** @returns {string} The current version. */
+    get version() {
+        checkDestroy(this.#isDestroyed);
+        return this.#version;
+    }
+    /** @returns {ServiceWorkerRegistration | null} The current registration object. */
+    get registration() {
+        checkDestroy(this.#isDestroyed);
+        return this.#registration;
+    }
+    /** @type {Set<EventListener>} A set of registered event listeners. */
+    #eventListeners = new Set();
+    /**
+     * Returns a list of all registered event callbacks.
+     * @returns {EventListener[]} An array of event listeners.
+     */
+    get eventListeners() {
+        checkDestroy(this.#isDestroyed);
+        return Array.from(this.#eventListeners);
+    }
+    /**
+     * Determines the current PWA display mode.
+     * @returns {'twa' | 'standalone' | 'browser'} The current display mode.
+     */
+    get displayMode() {
+        checkDestroy(this.#isDestroyed);
+        return this.#displayMode;
+    }
+    /** @type {boolean} Indicates if the browser should automatically show a notification when a push is received in browser mode. */
+    #autoNotifyPush = true;
+    /** @returns {boolean} True if auto-notification is enabled. */
+    get autoNotifyPush() {
+        checkDestroy(this.#isDestroyed);
+        return this.#autoNotifyPush;
+    }
+    /** @param {boolean} value - Whether to enable auto-notification. */
+    set autoNotifyPush(value) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof value !== 'boolean') {
+            throw new TypeError('autoNotifyPush must be a boolean.');
+        }
+        this.#autoNotifyPush = value;
+    }
+    /**
+     * Returns a copy of the blacklisted event names.
+     * @returns {string[]} An array with every blacklisted event name.
+     */
+    get eventBlacklist() {
+        checkDestroy(this.#isDestroyed);
+        return Array.from(this.#eventBlacklist);
+    }
+    /**
+     * Adds an event name to the blacklist. Blacklisted events are ignored when
+     * they arrive from the Service Worker.
+     * @param {string} type - The event name to ignore.
+     * @returns {void}
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    addToEventBlacklist(type) {
+        checkDestroy(this.#isDestroyed);
+        TinyServiceWorker.#assertEventName(type);
+        this.#eventBlacklist.add(type);
+    }
+    /**
+     * Removes an event name from the blacklist.
+     * @param {string} type - The event name to remove.
+     * @returns {boolean} True if the event was removed, false otherwise.
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    removeFromEventBlacklist(type) {
+        checkDestroy(this.#isDestroyed);
+        TinyServiceWorker.#assertEventName(type);
+        return this.#eventBlacklist.delete(type);
+    }
+    /**
+     * Checks whether an event name is blacklisted.
+     * @param {string} type - The event name to check.
+     * @returns {boolean} True if the event is blacklisted, false otherwise.
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    hasInEventBlacklist(type) {
+        checkDestroy(this.#isDestroyed);
+        TinyServiceWorker.#assertEventName(type);
+        return this.#eventBlacklist.has(type);
+    }
+    /**
+     * Removes every event name from the blacklist.
+     * @returns {void}
+     */
+    clearEventBlacklist() {
+        checkDestroy(this.#isDestroyed);
+        this.#eventBlacklist.clear();
+    }
+    /**
+     * @param {Object} options - Configuration options for the instance.
+     * @param {IdWorker} options.id - The unique identifier for this manager instance.
+     * @param {SwUrl} options.swUrl - The path to the service worker file.
+     * @param {string} options.version - The current application version.
+     * @param {boolean} [options.debugMode=false] - Whether to enable internal debug logging.
+     * @param {boolean} [options.useLogColors=false] - Whether to enable log color support.
+     * @param {Partial<Console>} [options.logger=console] - A custom logger object (must implement console methods).
+     * @throws {TypeError} If parameters are not the correct types or if id is empty.
+     */
+    constructor(options) {
+        if (Array.isArray(options) || typeof options !== 'object' || options === null) {
+            throw new TypeError('The "options" argument must be a non-null object.');
+        }
+        const { id, swUrl, version, logger, debugMode, useLogColors } = options;
+        if (typeof id !== 'string' || id.trim() === '') {
+            throw new TypeError('The "id" parameter must be a non-empty string.');
+        }
+        if (typeof swUrl !== 'string' && !(swUrl instanceof URL)) {
+            throw new TypeError('The "swUrl" parameter must be a string or URL.');
+        }
+        if (typeof version !== 'string') {
+            throw new TypeError('The "version" parameter must be a string.');
+        }
+        super({
+            logCfg: {
+                id: '[_sub_class_TinyServiceWorker_reset_]',
+                logger: logger ?? console,
+                debugMode: debugMode ?? false,
+                useLogColors: useLogColors ?? false,
+            },
+        });
+        this.#id = id;
+        this.#swUrl = swUrl;
+        this.#version = version;
+        this.#updateDisplayMode();
+    }
+    /**
+     * Updates the internal displayMode state and emits an event.
+     */
+    #updateDisplayMode() {
+        const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
+        const isTwa = document.referrer.startsWith('android-app://');
+        if (isTwa) {
+            this.#displayMode = 'twa';
+            // @ts-ignore
+        }
+        else if (navigator.standalone || isStandalone) {
+            this.#displayMode = 'standalone';
+        }
+        else {
+            this.#displayMode = 'browser';
+        }
+        this.emit('sw:DisplayModeChanged', { displayMode: this.#displayMode });
+        this.log('info', `DISPLAY_MODE_CHANGED: ${this.#displayMode}`);
+    }
+    /**
+     * Sets up listeners for PWA lifecycle events.
+     */
+    #setupPwaListeners() {
+        // 1. Handle Display Mode Changes
+        this.#displayModeChangeHandler = () => this.#updateDisplayMode();
+        window
+            .matchMedia('(display-mode: standalone)')
+            .addEventListener('change', this.#displayModeChangeHandler);
+        // 2. Handle Before Install Prompt
+        this.#beforeInstallPromptHandler = (e) => {
+            // @ts-ignore
+            this.#deferredPrompt = e;
+            this.emit('sw:BeforeInstallPrompt', { event: e });
+            this.log('info', 'beforeinstallprompt event fired.');
+        };
+        window.addEventListener('beforeinstallprompt', this.#beforeInstallPromptHandler);
+        // 3. Handle App Installed
+        this.#appInstalledHandler = () => {
+            this.#deferredPrompt = null;
+            this.emit('sw:AppInstalled');
+            this.log('info', 'PWA was installed');
+        };
+        window.addEventListener('appinstalled', this.#appInstalledHandler);
+    }
+    /**
+     * Triggers the native PWA installation prompt.
+     * @returns {Promise<void>} A promise that resolves when the prompt has been shown.
+     * @throws {Error} If the prompt cannot be shown because the `beforeinstallprompt` event has not fired.
+     */
+    async promptInstallation() {
+        checkDestroy(this.#isDestroyed);
+        if (!this.#deferredPrompt) {
+            throw new Error('Cannot show installation prompt: beforeinstallprompt event has not fired.');
+        }
+        this.#deferredPrompt.prompt();
+        const { outcome } = await this.#deferredPrompt.userChoice;
+        this.log('info', `User installation choice: ${outcome}`);
+        this.#deferredPrompt = null;
+    }
+    /**
+     * Returns a promise that resolves when the Service Worker is fully registered,
+     * initialized, and has taken control of the current page.
+     * @returns {Promise<void>} A promise that resolves when the Service Worker is ready for use.
+     * @throws {Error} If the Service Worker registration fails.
+     */
+    async waitForReady() {
+        checkDestroy(this.#isDestroyed);
+        // 1. If registration already failed, reject immediately.
+        if (this.#isFailed) {
+            throw new Error('Service Worker registration failed. Cannot wait for ready state.');
+        }
+        // 2. If already ready and controlling the page, resolve immediately.
+        if (this.#isReady && navigator.serviceWorker.controller) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            /**
+             * Handler for when the Service Worker takes control of the page.
+             */
+            const onControllerChange = () => {
+                // Once the controller changes, check if the class is ready and the worker is controlling.
+                if (this.#isReady && navigator.serviceWorker.controller) {
+                    cleanup();
+                    resolve();
+                }
+            };
+            /**
+             * Handler for when a registration error occurs during the wait.
+             * @param {Error} error - The error thrown during registration.
+             */
+            const onRegistrationFailed = (error) => {
+                cleanup();
+                reject(error instanceof Error ? error : new Error(String(error)));
+            };
+            /**
+             * Cleans up event listeners to prevent memory leaks.
+             */
+            const cleanup = () => {
+                navigator.serviceWorker.removeEventListener('controllerchange', onControllerChange);
+                this.off('sw:RegistrationFailed', onRegistrationFailed);
+            };
+            // Listen for the 'controllerchange' event to know when the SW is in control.
+            navigator.serviceWorker.addEventListener('controllerchange', onControllerChange);
+            this.on('sw:RegistrationFailed', onRegistrationFailed);
+            // 3. Safety check: if it became ready between the initial check and adding the listener.
+            if (this.#isReady && navigator.serviceWorker.controller) {
+                cleanup();
+                resolve();
+            }
+        });
+    }
+    /**
+     * Registers a new sync tag to be handled by the Service Worker.
+     * This will trigger the 'sync' event in the Service Worker when connectivity is available.
+     *
+     * @param {string} tag - A unique identifier for the sync task.
+     * @returns {Promise<void>} A promise that resolves when the sync registration is successful.
+     * @throws {Error} If Background Sync is not supported by the browser.
+     * @throws {TypeError} If the tag is not a non-empty string.
+     */
+    async registerSync(tag) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof tag !== 'string' || tag.trim() === '') {
+            throw new TypeError('[TinyServiceWorker] registerSync: tag must be a non-empty string.');
+        }
+        // 1. Wait for the service worker to be active/ready
+        const registration = await TinyServiceWorker.waitForReady();
+        if (!registration.sync) {
+            throw new Error('[TinyServiceWorker] registerSync: Background Sync API is not supported in this browser.');
+        }
+        try {
+            // 2. Register the sync tag
+            await registration.sync.register(tag);
+            this.log('info', `Sync tag registered: ${tag}`);
+        }
+        catch (error) {
+            this.log('error', `Failed to register sync tag "${tag}":`, error);
+            throw error;
+        }
+    }
+    /**
+     * Requests permission from the user to display notifications.
+     *
+     * @returns {Promise<'granted' | 'denied' | 'default'>} The resulting permission status.
+     * @throws {Error} If the Notification API is not supported by the browser.
+     */
+    async requestNotificationPermission() {
+        checkDestroy(this.#isDestroyed);
+        try {
+            const permission = await requestNotificationPermission();
+            // If permission is already 'granted', return immediately.
+            if (permission === 'granted') {
+                this.emit('sw:NotificationPermissionChanged', { permission: 'granted' });
+                return permission;
+            }
+            // If 'denied', the user has blocked it and we cannot prompt again via code.
+            else if (permission === 'denied') {
+                this.log('warn', 'Notification permission was denied by the user.');
+                this.emit('sw:NotificationPermissionChanged', { permission: 'denied' });
+                return permission;
+            }
+            // Emit an event so the UI can react (e.g., show/hide notification settings).
+            this.log('info', `Notification permission status: ${permission}`);
+            this.emit('sw:NotificationPermissionChanged', { permission });
+            return permission;
+        }
+        catch (error) {
+            this.log('error', 'Error requesting notification permission:', error);
+            throw error;
+        }
+    }
+    /**
+     * Handles a push message forwarded by the Service Worker.
+     *
+     * The method never shows a notification on its own. It always emits the
+     * `push` event with a `showNotification` helper, so the consumer decides
+     * whether the page must display a fallback notification or not.
+     *
+     * @param {TinyPushMessage & { notificationShown?: boolean }} pushData - The payload sent by the Service Worker.
+     * @param {MessageEvent} event - The original message event.
+     * @returns {void}
+     */
+    #handlePushReceived(pushData, event) {
+        const notificationShown = pushData.notificationShown === true;
+        /** @type {import('../utils.mjs').TinyPushNotification|null} */
+        const swNotification = pushData.notification ?? null;
+        /**
+         * Renders the notification in the page and wires the round trip back to the SW.
+         * @param {Partial<import('./TinyNotificationAdapter.mjs').BrowserNotificationOptions>} [overrides]
+         * @returns {Notification|null}
+         */
+        const showNotification = (overrides = {}) => {
+            if (!('Notification' in window)) {
+                this.log('warn', 'Push received, but the Notification API is not supported.');
+                return null;
+            }
+            // SW -> Browser
+            const browserNotification = TinyNotificationAdapter.toBrowser(swNotification, overrides);
+            const instance = new Notification(browserNotification.title, browserNotification.options);
+            // Browser -> SW
+            /** @param {string} type */
+            const sendBack = (type) => {
+                const payload = TinyNotificationAdapter.toServiceWorker(browserNotification);
+                this.#emitMessage(type, payload, false);
+            };
+            instance.onclick = () => sendBack('sw:NotificationClicked');
+            instance.onclose = () => sendBack('sw:NotificationClosed');
+            return instance;
+        };
+        // The page only shows a fallback when the Service Worker did not.
+        if (!notificationShown && this.displayMode === 'browser' && this.#autoNotifyPush) {
+            showNotification();
+        }
+        this.#pushEvents.emit(pushData.topic ?? 'push', {
+            data: { ...pushData, notificationShown },
+            event,
+            notificationShown,
+            showNotification,
+        });
+    }
+    /**
+     * Registers the service worker and handles version updates.
+     * @param {RegistrationOptions} [options] - Standard Service Worker registration options.
+     * @returns {Promise<void>} A promise that resolves when registration is attempted.
+     * @throws {Error} If the registration process encounters an error.
+     */
+    async register(options) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof options !== 'undefined' &&
+            (Array.isArray(options) || typeof options !== 'object' || options === null)) {
+            throw new TypeError('The "options" argument must be a non-null object.');
+        }
+        if (!('serviceWorker' in navigator)) {
+            this.log('warn', 'Service Worker is not supported in this browser.');
+            return;
+        }
+        try {
+            const idVersion = `${this.#id}_sw_version`;
+            const savedVersion = localStorage.getItem(idVersion);
+            // Check if a version mismatch exists
+            if (savedVersion !== this.#version) {
+                this.log('warn', `Version mismatch detected: ${savedVersion} -> ${this.#version}. Signaling update...`);
+                // 1. Notify the UI that a new version is available (to show the update button)
+                this.emit('sw:VersionUpdateAvailable');
+                // 2. Signal the current Service Worker to begin downloading the new version
+                this.#emitMessage('sw:PrepareUpdate');
+                // Update localStorage so subsequent manual refreshes recognize the new version
+                localStorage.setItem(idVersion, this.#version);
+            }
+            const swUrl = new URL(this.#swUrl, location.origin);
+            swUrl.searchParams.set('v', this.#version);
+            if (this.debugMode) {
+                // Using searchParams.set is more robust than manual string concatenation.
+                // It automatically handles whether to use '?' or '&' as a separator.
+                swUrl.searchParams.set('t', Date.now().toString());
+            }
+            this.#registration = await navigator.serviceWorker.register(swUrl.toString(), options);
+            // Listen for when the new Service Worker takes control
+            navigator.serviceWorker.addEventListener('controllerchange', (event) => {
+                this.emit('sw:NewVersionReady', { event });
+                this.log('info', 'New Service Worker is now in control.');
+            });
+            // Existing message handler and lifecycle logic
+            this.#messageHandler = (event) => {
+                /** @type {ServiceWorkerMessagePayload & { correlationId?: string; error?: string; isApi?: boolean; }} */
+                const payload = event.data;
+                if (Array.isArray(payload) || typeof payload !== 'object' || payload === null)
+                    return;
+                if (typeof payload.type !== 'string')
+                    return;
+                if (this.#eventBlacklist.has(payload.type)) {
+                    this.log('warn', `Ignored blacklisted event: ${payload.type}`);
+                    return;
+                }
+                if (typeof payload.data !== 'undefined' &&
+                    (Array.isArray(payload.data) || typeof payload.data !== 'object' || payload.data === null))
+                    return;
+                // 1. Push events forwarded by the Service Worker
+                if (payload.type === 'sw:PushReceived') {
+                    this.#handlePushReceived(payload.data, event);
+                    return;
+                }
+                // 2. Logic to respond to API calls (Response from SW -> Browser)
+                if (payload.type === 'sw:ApiResponse') {
+                    if (typeof payload.correlationId !== 'string') {
+                        this.log('error', 'Received message with missing or invalid "correlationId" string.');
+                        return;
+                    }
+                    const pending = this.#pendingRequests.get(payload.correlationId);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        this.#pendingRequests.delete(payload.correlationId);
+                        if (payload.error) {
+                            pending.reject(new Error(payload.error));
+                        }
+                        else {
+                            pending.resolve(payload.data);
+                        }
+                    }
+                    return;
+                }
+                // 3. Logic to RECEIVE API requests (Request from SW -> Browser)
+                if (payload.isApi === true) {
+                    if (typeof payload.correlationId !== 'string') {
+                        this.log('error', 'Received message with missing or invalid "correlationId" string.');
+                        return;
+                    }
+                    const handler = this.#apiHandlers.get(payload.type);
+                    if (!handler) {
+                        postMessage({
+                            correlationId: payload.correlationId,
+                            type: 'sw:ApiResponse',
+                            error: `No API handler registered for type: ${payload.type}`,
+                        });
+                        return;
+                    }
+                    try {
+                        /** @param {MessagePayload} [r] */
+                        const sendResult = (r) => postMessage({
+                            correlationId: payload.correlationId,
+                            type: 'sw:ApiResponse',
+                            data: r,
+                        });
+                        const result = handler({ data: payload.data, correlationId: payload.correlationId });
+                        if (result instanceof Promise)
+                            result.then(sendResult);
+                        else
+                            sendResult(result);
+                    }
+                    catch (error) {
+                        postMessage({
+                            correlationId: payload.correlationId,
+                            type: 'sw:ApiResponse',
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    return;
+                }
+                this.emit(payload.type, { data: payload.data, event });
+            };
+            navigator.serviceWorker.addEventListener('message', this.#messageHandler);
+            // Initialize PWA listeners
+            this.#setupPwaListeners();
+            this.#isReady = true;
+            this.log('info', 'Registered successfully.');
+        }
+        catch (error) {
+            this.#isFailed = true;
+            this.log('error', 'Registration error:', error);
+        }
+    }
+    /**
+     * Unregisters the Service Worker from the browser and destroys the manager instance.
+     * @returns {Promise<boolean>} A promise that resolves to `true` if the Service Worker
+     * was successfully unregistered, or `false` otherwise.
+     * @throws {Error} If an unexpected error occurs during the unregistration process.
+     */
+    async unregister() {
+        checkDestroy(this.#isDestroyed);
+        if (!this.#registration) {
+            this.log('warn', 'No active ServiceWorkerRegistration found to unregister.');
+            this.destroy();
+            return false;
+        }
+        try {
+            const success = await this.#registration.unregister();
+            if (success) {
+                this.log('info', 'Service Worker unregistered successfully.');
+            }
+            else {
+                this.log('warn', 'The unregister() method returned false (the worker might already be inactive).');
+            }
+            // Call destroy to clean up event listeners and references
+            this.destroy();
+            return success;
+        }
+        catch (error) {
+            this.log('error', 'Error during Service Worker unregistration:', error);
+            throw error;
+        }
+    }
+    /**
+     * Sends a message to the active Service Worker controller.
+     * @param {string} type - The identifier for the message type.
+     * @param {MessagePayload} [data] - The actual data content of the message.
+     * @param {boolean} [strictMode=false] - Enable strict mode validator.
+     * @returns {boolean} True if the message was sent, false otherwise.
+     * @throws {TypeError} If the type is not a string or data is not a non-null object.
+     */
+    #emitMessage(type, data, strictMode = false) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof type !== 'string') {
+            throw new TypeError('Payload.type must be a string.');
+        }
+        if (typeof strictMode !== 'boolean') {
+            throw new TypeError('The "strictMode" argument must be a boolean.');
+        }
+        if (typeof data !== 'undefined' &&
+            (Array.isArray(data) || typeof data !== 'object' || data === null)) {
+            throw new TypeError('Payload.data must be a non-null object.');
+        }
+        // Security check: prevent sending messages that collide with internal events
+        if (strictMode)
+            TinyServiceWorker.#validateEventType(type);
+        if ('serviceWorker' in navigator && !!navigator.serviceWorker.controller) {
+            navigator.serviceWorker.controller.postMessage({ type, data });
+            return true;
+        }
+        else {
+            this.#noSwControllerWarn();
+            return false;
+        }
+    }
+    /**
+     * Removes a registered API handler.
+     * @param {string} type - The call identifier.
+     * @returns {boolean} True if a handler was removed, false otherwise.
+     * @throws {TypeError} If the type is not a non-empty string.
+     */
+    offApi(type) {
+        if (typeof type !== 'string' || type.trim() === '') {
+            throw new TypeError('The "type" argument must be a non-empty string.');
+        }
+        return this.#apiHandlers.delete(type);
+    }
+    /**
+     * Registers a handler for API calls coming from the Service Worker.
+     * @param {string} type - The call identifier.
+     * @param {ApiHandlerCallback} callback - Function that processes the request and returns the result.
+     * @returns {void}
+     * @throws {TypeError} If the type is not a non-empty string.
+     * @throws {TypeError} If the callback is not a function.
+     */
+    onApi(type, callback) {
+        if (typeof type !== 'string' || type.trim() === '') {
+            throw new TypeError('The "type" argument must be a non-empty string.');
+        }
+        if (typeof callback !== 'function') {
+            throw new TypeError('Callback must be a function.');
+        }
+        this.#apiHandlers.set(type, callback);
+    }
+    /**
+     * Sends a message to the active Service Worker and waits for a response via Promise.
+     * @param {string} type - The API call identifier.
+     * @param {MessagePayload} [data] - The request payload.
+     * @param {number} [timeout=10000] - Maximum waiting time in milliseconds.
+     * @returns {Promise<any>} A promise that resolves with the result object or undefined from the Service Worker.
+     * @throws {TypeError} If the type is not a non-empty string.
+     * @throws {TypeError} If the data is not a non-null object.
+     * @throws {TypeError} If the timeout is not a number.
+     * @throws {RangeError} If the timeout is not a finite number greater than or equal to 0.
+     * @throws {Error} If the timeout is reached or if the Service Worker is unavailable.
+     */
+    async emitApi(type, data, timeout = 10000) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof type !== 'string' || type.trim() === '') {
+            throw new TypeError('The "type" argument must be a non-empty string.');
+        }
+        if (typeof data !== 'undefined' &&
+            (Array.isArray(data) || typeof data !== 'object' || data === null)) {
+            throw new TypeError('The "data" argument must be a non-null object.');
+        }
+        if (typeof timeout !== 'number') {
+            throw new TypeError('The "timeout" argument must be a number.');
+        }
+        if (!Number.isFinite(timeout) || timeout < 0) {
+            throw new RangeError('The "timeout" argument must be a finite number greater than or equal to 0.');
+        }
+        const correlationId = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.#pendingRequests.has(correlationId)) {
+                    this.#pendingRequests.delete(correlationId);
+                    reject(new Error(`API request timeout: ${type} (ID: ${correlationId})`));
+                }
+            }, timeout);
+            this.#pendingRequests.set(correlationId, { resolve, reject, timer });
+            postMessage({
+                type,
+                data,
+                correlationId,
+                isApi: true,
+            });
+        });
+    }
+    /**
+     * Sends a message to the active Service Worker controller.
+     * @param {string} type - The identifier for the message type.
+     * @param {MessagePayload} [data] - The actual data content of the message.
+     * @returns {boolean} True if the message was sent, false otherwise.
+     * @throws {TypeError} If the type is not a string or data is not a non-null object.
+     */
+    emitMessage(type, data) {
+        return this.#emitMessage(type, data, true);
+    }
+    /**
+     * Sends a message to the active Service Worker controller using a full payload.
+     * @param {ServiceWorkerMessagePayload} payload - The message payload.
+     * @throws {TypeError} If the payload is not an object, type is not a string, or data is not a non-null object.
+     */
+    postMessage(payload) {
+        checkDestroy(this.#isDestroyed);
+        if (Array.isArray(payload) || typeof payload !== 'object' || payload === null) {
+            throw new TypeError('Payload must be an object.');
+        }
+        if (typeof payload.type !== 'string') {
+            throw new TypeError('Payload.type must be a string.');
+        }
+        if (typeof payload.data !== 'undefined' &&
+            (Array.isArray(payload.data) || typeof payload.data !== 'object' || payload.data === null)) {
+            throw new TypeError('Payload.data must be a non-null object.');
+        }
+        // Security check: prevent sending messages that collide with internal events
+        TinyServiceWorker.#validateEventType(payload.type);
+        if ('serviceWorker' in navigator && !!navigator.serviceWorker.controller) {
+            navigator.serviceWorker.controller.postMessage(payload);
+        }
+        else
+            this.#noSwControllerWarn();
+    }
+    /**
+     * Adds an event listener for messages from the Service Worker.
+     * @param {EventListener} callback - The callback function to be invoked.
+     * @throws {TypeError} If the callback is not a function.
+     */
+    addEventListener(callback) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof callback !== 'function') {
+            throw new TypeError('The callback must be a function.');
+        }
+        if ('serviceWorker' in navigator) {
+            navigator.serviceWorker.addEventListener('message', callback);
+            this.#eventListeners.add(callback);
+        }
+        else
+            this.#noSwControllerWarn();
+    }
+    /**
+     * Removes an event listener from the Service Worker.
+     * @param {EventListener} callback - The callback to be removed.
+     * @returns {boolean} True if the event listener was removed, false otherwise.
+     * @throws {TypeError} If the callback is not a function.
+     */
+    removeEventListener(callback) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof callback !== 'function') {
+            throw new TypeError('The callback must be a function.');
+        }
+        if ('serviceWorker' in navigator) {
+            navigator.serviceWorker.removeEventListener('message', callback);
+            return this.#eventListeners.delete(callback);
+        }
+        else
+            this.#noSwControllerWarn();
+        return false;
+    }
+    /**
+     * Cleans up all event listeners and references to prevent memory leaks.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#isDestroyed)
+            return;
+        // 1. Remove native Service Worker listener
+        if ('serviceWorker' in navigator) {
+            if (this.#messageHandler) {
+                navigator.serviceWorker.removeEventListener('message', this.#messageHandler);
+                this.#messageHandler = null;
+            }
+            for (const callback of this.#eventListeners) {
+                navigator.serviceWorker.removeEventListener('message', callback);
+            }
+            this.#eventListeners.clear();
+        }
+        // 2. Remove Window Listeners (Crucial for preventing memory leaks)
+        if (this.#displayModeChangeHandler) {
+            window
+                .matchMedia('(display-mode: standalone)')
+                .removeEventListener('change', this.#displayModeChangeHandler);
+            this.#displayModeChangeHandler = null;
+        }
+        if (this.#beforeInstallPromptHandler) {
+            window.removeEventListener('beforeinstallprompt', this.#beforeInstallPromptHandler);
+            this.#beforeInstallPromptHandler = null;
+        }
+        if (this.#appInstalledHandler) {
+            window.removeEventListener('appinstalled', this.#appInstalledHandler);
+            this.#appInstalledHandler = null;
+        }
+        // 3. Remove EventEmitter listeners
+        this.removeAllListeners();
+        this.#pushEvents.removeAllListeners();
+        // 4. Clear references
+        this.#registration = null;
+        this.#deferredPrompt = null;
+        this.destroyPlugins();
+        this.#isDestroyed = true;
+        this.log('info', `[${this.#id}] Destroyed successfully.`);
+    }
+}
+export default TinyServiceWorker;