tiny-essentials 1.28.19 → 1.29.0

package/dist/v1/libs/sw/service/TinyServiceWorkerEngine.cjs

@@ -0,0 +1,3016 @@
+'use strict';
+
+var TinyPushRouter = require('./TinyPushRouter.cjs');
+var TinyPushPayload = require('./shared/TinyPushPayload.cjs');
+var SegmentExtractor = require('../../../regexp/SegmentExtractor.cjs');
+var TinyCloner = require('../../utils/TinyCloner.cjs');
+var BrowserNONDOM = require('../../tools/TinyHttpResponseRegistry/Browser-NON-DOM.cjs');
+var TinyPlugin = require('../../plugin/TinyPlugin.cjs');
+var utils = require('../utils.cjs');
+
+const codeIs = BrowserNONDOM.codeIs;
+
+/** @type {readonly InstallStrategy[]} The list of accepted install strategies. */
+const INSTALL_STRATEGIES = Object.freeze(['immediate', 'wait', 'manual']);
+
+/** @type {readonly ActivateStrategy[]} The list of accepted activate strategies. */
+const ACTIVATE_STRATEGIES = Object.freeze(['immediate', 'wait', 'manual']);
+
+/** @type {readonly LifecycleOrder[]} The list of accepted lifecycle orders. */
+const LIFECYCLE_ORDERS = Object.freeze(['before', 'after']);
+
+/**
+ * Single source of truth for the lifecycle options: every entry pairs the
+ * property name with the list of values it accepts.
+ *
+ * @type {readonly (readonly [string, readonly string[]])[]}
+ */
+const LIFECYCLE_SPEC = Object.freeze([
+  ['installStrategy', INSTALL_STRATEGIES],
+  ['activateStrategy', ACTIVATE_STRATEGIES],
+  ['installOrder', LIFECYCLE_ORDERS],
+  ['activateOrder', LIFECYCLE_ORDERS],
+]);
+
+/**
+ * Maps each lifecycle phase to the {@link LifecycleOptions} key that stores the
+ * order of that phase. Keeping the mapping explicit lets the type checker prove
+ * that every phase resolves to a valid key.
+ *
+ * @type {Readonly<Record<'install'|'activate', 'installOrder'|'activateOrder'>>}
+ */
+const PHASE_ORDER_KEY = Object.freeze({
+  install: 'installOrder',
+  activate: 'activateOrder',
+});
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * Describes a single entry of the {@link GlobalMsgCode} table.
+ *
+ * Each entry maps an internal HTTP status code (or the `unknown` fallback) to the
+ * information required to build a response and to log the occurrence.
+ *
+ * @template {string|null} Path - The type accepted by {@link GlobalMsgCodeItem.path}.
+ *   Use `string` for entries that serve a file and `null` for entries that must not
+ *   serve any file.
+ * @typedef {Object} GlobalMsgCodeItem
+ * @property {Path} path - Absolute path of the file served for this entry.
+ *   When the value is `null`, no file is fetched and the response is built from
+ *   {@link GlobalMsgCodeItem.msg} only.
+ * @property {string} msg - Short, human readable message. It is used as the response
+ *   body and as the `statusText` of the generated error response.
+ * @property {string} logMsg - Message written to the log. It is aimed at developers,
+ *   so it can be more descriptive than {@link GlobalMsgCodeItem.msg}.
+ */
+
+/**
+ * The complete message table used by the engine to answer a request.
+ *
+ * Every key except `spaPath` is an HTTP status code. The `unknown` key is the
+ * fallback used when a status code has no dedicated entry.
+ *
+ * @typedef {{ spaPath: string; unknown: GlobalMsgCodeItem<string>; 200: GlobalMsgCodeItem<null>; 404: GlobalMsgCodeItem<string>; 500: GlobalMsgCodeItem<string>; }} GlobalMsgCode
+ * @property {string} spaPath - Path served for every navigation request while
+ *   `spaMode` is `true`.
+ * @property {GlobalMsgCodeItem<string>} unknown - Fallback entry, used when no other
+ *   entry matches the status code.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * Enriched event object for the sync event.
+ * @typedef {Object} SyncEventObj
+ * @property {SyncEvent} event - The native sync event.
+ * @property {string} tag - The tag associated with the sync event.
+ */
+
+/**
+ * Callback for the sync handler.
+ * @callback SyncCallback
+ * @param {SyncEventObj} msg - The sync event object.
+ * @returns {Promise<void> | void} A promise that settles once the handler finishes, or nothing when the handler is synchronous.
+ */
+
+/**
+ * Enriched event object for the install and activate lifecycle events.
+ * @typedef {Object} LifecycleEventObj
+ * @property {ExtendableEvent} event - The native install or activate event.
+ */
+
+/**
+ * Callback for install and activate lifecycle handlers.
+ * @callback LifecycleCallback
+ * @param {LifecycleEventObj} msg - The lifecycle event object.
+ * @returns {Promise<void> | void} A promise that settles once the handler finishes, or nothing when the handler is synchronous.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * A function that handles the actual postMessage call to the message api source.
+ * @callback MessageApiReply
+ * @param {string} type - The type identifier for the api reply message.
+ * @param {MessagePayload} [data] - The payload to be sent in the api reply.
+ * @param {number} [timeout=10000] - Wait time.
+ * @returns {Promise<any>} A promise that resolves with the response payload sent back by the message source.
+ */
+
+/**
+ * Options object passed to every API handler registered through {@link TinyServiceWorkerEngine#onApi}.
+ * @typedef {Object} ApiHandlerOptions
+ * @property {MessagePayload} [data] - The payload received from the browser.
+ * @property {string} clientId - The ID of the client that sent the message.
+ * @property {string} correlationId - The request ID.
+ * @property {MessageReplyTo} replyTo - A function to send a reply to the message source.
+ * @property {MessageReplyToAll} replyToAll - A function to send a reply to all clients.
+ * @property {MessageReplyTemplate} replyTemplate - A template function to format reply messages.
+ * @property {MessageReply} reply - A convenience method to reply to the message source.
+ * @property {MessageApiReply} replyApi - A convenience method to reply to the message api source.
+ */
+
+/**
+ * Handles an API call received from the browser and returns the payload that must be sent back.
+ * @callback ApiHandlerCallback
+ * @param {ApiHandlerOptions} options - Options for the API handler.
+ * @returns {Promise<MessagePayload|undefined> | (MessagePayload|undefined)} The response payload.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * Strategy used to resolve the `install` phase of the Service Worker.
+ *
+ * - `immediate`: runs the install listeners and calls `skipWaiting()` right away.
+ * - `wait`: never calls `skipWaiting()`. The new worker stays in the `waiting`
+ *   state until every client is closed.
+ * - `manual`: does not call `skipWaiting()` automatically. The application must
+ *   call {@link TinyServiceWorkerEngine#skipWaiting} when it decides to.
+ *
+ * @typedef {'immediate'|'wait'|'manual'} InstallStrategy
+ */
+
+/**
+ * Strategy used to resolve the `activate` phase of the Service Worker.
+ *
+ * - `immediate`: runs the activate listeners and calls `clients.claim()` right away.
+ * - `wait`: never calls `clients.claim()`.
+ * - `manual`: does not call `clients.claim()` automatically.
+ *
+ * @typedef {'immediate'|'wait'|'manual'} ActivateStrategy
+ */
+
+/**
+ * Determines whether the lifecycle strategy of a phase runs before or after
+ * the user-registered listeners of that same phase.
+ *
+ * - `before`: the strategy (`skipWaiting()` / `clients.claim()`) is resolved
+ *   first, then the listeners run.
+ * - `after`: the listeners run first, then the strategy is resolved.
+ *
+ * @typedef {'before'|'after'} LifecycleOrder
+ */
+
+/**
+ * Lifecycle configuration for the engine.
+ *
+ * @typedef {Object} LifecycleOptions
+ * @property {InstallStrategy} installStrategy - How the `install` phase is resolved.
+ * @property {ActivateStrategy} activateStrategy - How the `activate` phase is resolved.
+ * @property {LifecycleOrder} installOrder - Order of the strategy inside the `install` phase.
+ * @property {LifecycleOrder} activateOrder - Order of the strategy inside the `activate` phase.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+/**
+ * A partial configuration object for Service Worker settings.
+ * @typedef {Object} PartialServiceWorkerSettings
+ * @property {boolean} [spaMode] - Whether the service worker is running in Single Page Application mode.
+ * @property {Partial<LifecycleOptions>} [lifecycle] - Partial lifecycle configuration.
+ * @property {PartialFetchOptions} fetch - Partial configuration for fetch event interception.
+ * @property {PartialPushOptions} push - Partial configuration for push event interception.
+ * @property {PartialSyncOptions} sync - Partial configuration for sync event interception.
+ * @property {Partial<MessagingOptions>} messaging - Partial configuration for message event handling.
+ */
+
+/**
+ * A partial configuration object for background sync interception settings.
+ * @typedef {Object} PartialSyncOptions
+ * @property {boolean} [enabled] - Indicates if sync interception is enabled.
+ */
+
+/**
+ * A partial configuration object for push interception settings.
+ * @typedef {Object} PartialPushOptions
+ * @property {boolean} [enabled] - Indicates if push interception is enabled.
+ * @property {string} [vapidPublicKey] - Base64 URL-safe VAPID public key.
+ * @property {string} [subscribeEndpoint] - Backend route that persists subscriptions.
+ * @property {string} [defaultIcon] - Fallback notification icon.
+ * @property {string} [defaultBadge] - Fallback notification badge.
+ * @property {string} [defaultUrl] - Fallback click URL.
+ */
+
+/**
+ * A partial configuration object for fetch interception settings.
+ * @typedef {Object} PartialFetchOptions
+ * @property {boolean} [enabled] - Indicates if fetch interception is enabled.
+ * @property {Partial<RouterOptions>} router - Partial configuration for the routing logic.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * Configuration settings for intercepting and handling fetch events.
+ * @typedef {Object} FetchOptions
+ * @property {boolean} enabled - Indicates if fetch interception is enabled.
+ * @property {RouterOptions} router - Configuration for the routing logic.
+ */
+
+/**
+ * Configuration settings for intercepting and handling push events.
+ * @typedef {Object} PushOptions
+ * @property {boolean} enabled - Indicates if push interception is enabled.
+ * @property {string} vapidPublicKey - Base64 URL-safe VAPID public key.
+ * @property {string} subscribeEndpoint - Backend route that persists subscriptions.
+ * @property {string} defaultIcon - Fallback notification icon.
+ * @property {string} defaultBadge - Fallback notification badge.
+ * @property {string} defaultUrl - Fallback click URL.
+ */
+
+/**
+ * Configuration settings for handling message communication.
+ * @typedef {Object} MessagingOptions
+ * @property {boolean} enabled - Indicates if message communication is enabled.
+ */
+
+/**
+ * Configuration settings for background sync event interception.
+ * @typedef {Object} SyncOptions
+ * @property {boolean} enabled - Indicates if sync interception is enabled.
+ */
+
+/**
+ * Configuration settings for the routing logic used during fetch interception.
+ * @typedef {Object} RouterOptions
+ * @property {boolean} enabled - Indicates if the router is active.
+ * @property {Map<number, RouterCodeConfig>} codes - A map linking HTTP status codes to their respective configurations.
+ */
+
+/**
+ * The complete configuration structure for the Service Worker engine.
+ * @typedef {Object} ServiceWorkerSettings
+ * @property {boolean} spaMode - Whether the service worker is running in Single Page Application mode.
+ * @property {LifecycleOptions} lifecycle - Lifecycle strategy configuration.
+ * @property {FetchOptions} fetch - Configuration for fetch event interception.
+ * @property {PushOptions} push - Configuration for push event interception.
+ * @property {SyncOptions} sync - Configuration for background sync event interception.
+ * @property {MessagingOptions} messaging - Configuration for message event handling.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * A function that transforms a given path string into another string.
+ * @callback PathGetter
+ * @param {string} path - The original path string to be transformed.
+ * @returns {string} The transformed path string.
+ */
+
+/**
+ * Data associated with a default HTTP status code response.
+ * @typedef {Object} DefaultCodeData
+ * @property {PathGetter} pathGetter - A function to retrieve the path for a given input.
+ * @property {RouterCodeConfig} data - The configuration data for the default response.
+ */
+
+/**
+ * Options object passed to the fetch handler function.
+ * @typedef {Object} FnOptions
+ * @property {FetchEvent} event - The fetch event being handled.
+ * @property {Request} request - The request object from the fetch event.
+ * @property {URL} url - The parsed URL of the request.
+ * @property {HttpResponseType} resType - The categorized response type.
+ * @property {string} [customMsg] - A custom error message.
+ * @property {string} [customPath] - A custom page path.
+ * @property {number} code - The HTTP status code.
+ */
+
+/**
+ * Configuration for a specific HTTP status code response handler.
+ * @typedef {Object} RouterCodeConfig
+ * @property {(ops: FnOptions) => Promise<Response> | Response} fn - The function executed to handle the request.
+ * @property {string} msg - The message string to be sent in the response.
+ * @property {string} logMsg - The log message to be recorded.
+ */
+
+/**
+ * Represents the raw values returned by a fetch checker.
+ * @typedef {Object} FetchCheckerValues
+ * @property {number} code - The HTTP status code associated with the fetch result.
+ * @property {boolean} needValidation - Whether the router must build a response for the current request.
+ * @property {boolean} continueCheck - Whether the next registered fetch listener is still allowed to run.
+ * @property {string} [customPath] - Overrides the path served by the router for this request.
+ * @property {string} [customMsg] - Overrides the message attached to the generated response.
+ */
+
+/**
+ * The enriched result from a fetch checker, combining base values with additional data.
+ * @typedef {FetchCheckerValues & { [id:string]:any}} FetchCheckerResult
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * The data payload contained within the message.
+ * @typedef {any} MessagePayload
+ */
+
+/**
+ * Represents the structured data format for messages sent via postMessage.
+ * @typedef {Object} MessagingData
+ * @property {string} type - The identifier for the message type.
+ * @property {MessagePayload} [data] - The actual payload of the message.
+ */
+
+/**
+ * A function used to format a reply message into a standard MessagingData object.
+ * @callback MessageReplyTemplate
+ * @param {string} type - The type identifier for the reply message.
+ * @param {MessagePayload} [data] - The payload to be sent in the reply.
+ * @returns {MessagingData} The formatted message object.
+ */
+
+/**
+ * A function that handles the actual postMessage call to a specific Client.
+ * @callback MessageReplyTo
+ * @param {Client} client - The target client to receive the message.
+ * @param {string} type - The type identifier for the reply message.
+ * @param {MessagePayload} [data] - The payload to be sent in the reply.
+ */
+
+/**
+ * Options accepted by the broadcast reply helpers, such as {@link TinyServiceWorkerEngine.replyToAll}.
+ * @typedef {Object} MessageReplyToAllOptions
+ * @property {string} type - The type identifier for the reply message.
+ * @property {MessagePayload} [data] - The payload to be sent in the reply.
+ * @property {ClientQueryOptions} [options] - Additional options for client matching.
+ */
+
+/**
+ * The result of a message broadcast operation.
+ * @typedef {Promise<void | readonly (Client | WindowClient)[]>} MessageReplyToAllResponse
+ */
+
+/**
+ * A function that handles the actual postMessage call to all Clients.
+ * @callback MessageReplyToAll
+ * @param {MessageReplyToAllOptions} options - The options for the reply.
+ * @returns {Promise<MessageReplyToAllResponse>} The result of the broadcast.
+ */
+
+/**
+ * A function that handles the actual postMessage call to the message source.
+ * @callback MessageReply
+ * @param {string} type - The type identifier for the reply message.
+ * @param {MessagePayload} [data] - The payload to be sent in the reply.
+ */
+
+/**
+ * An enriched message object containing the event, client information, and utility methods for responding.
+ * @typedef {Object} MessageObj
+ * @property {ExtendableMessageEvent} event - The original message event.
+ * @property {string} clientId - The ID of the client that sent the message.
+ * @property {MessagePayload} [data] - The payload sent within the message.
+ * @property {MessageReplyTo} replyTo - A function to send a reply to the message source.
+ * @property {MessageReplyToAll} replyToAll - A function to send a reply to all clients.
+ * @property {MessageReplyTemplate} replyTemplate - A template function to format reply messages.
+ * @property {MessageReply} reply - A convenience method to reply to the message source.
+ */
+
+/**
+ * A callback function executed when a registered message type is received.
+ * @callback MessageCallback
+ * @param {MessageObj} msg - The enriched message data object.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * A record of key-value pairs representing URL parameters extracted from a path.
+ * @typedef {Record<string, string>} FetchObjParams
+ */
+
+/**
+ * An enriched data object for fetch plugins.
+ * @typedef {Object} FetchObj
+ * @property {FetchEvent} event - The original fetch event.
+ * @property {Request} request - The intercepted request.
+ * @property {URL} url - The parsed URL of the request.
+ * @property {FetchObjParams} params - Parameters extracted from the URL (e.g., /:id).
+ * @property {MessageReplyTo} replyTo - A function to send a reply to the message source.
+ * @property {MessageReplyToAll} replyToAll - A function to send a reply to all clients.
+ * @property {MessageReplyTemplate} replyTemplate - A template function to format reply messages.
+ * @property {boolean} isSameOrigin - Indicates if the request is same-origin.
+ * @property {Error} [error] - An error object if the plugin execution failed.
+ */
+
+/**
+ * Callback function executed when the fetchUrls or fetchRegExp route matches.
+ * If it returns a boolean `false`, the interception is considered handled.
+ * @callback FetchCallback
+ * @param {FetchObj} fetchObj - The enriched request object.
+ * @param {FetchCheckerResult} result - The result of the fetch check.
+ * @returns {Promise<void>|void} A promise or value indicating if the request was handled.
+ */
+
+///////////////////////////////////////////////////////////////////
+
+/** @type {ServiceWorkerGlobalScope} The global scope of the Service Worker, aliased for readability. */
+// @ts-ignore
+const sw = self;
+
+/**
+ * Formats an error and its associated event into a standardized error object.
+ * @param {any} err - The error or value to be wrapped.
+ * @param {ExtendableEvent} event - The event associated with the error.
+ * @returns {{event: ExtendableEvent, error: Error}} An object containing the event and the error.
+ */
+const errorMaker = (err, event) => ({
+  event,
+  error: err instanceof Error ? err : new Error('Unknown Error'),
+});
+
+/**
+ * The category of an HTTP status code, used to route responses to the correct handler.
+ * @typedef {'info'|'success'|'redirect'|'client-error'|'server-error'|'unknown'} HttpResponseType
+ */
+
+/**
+ * Maps an HTTP status code to its corresponding response type category.
+ * @param {number} code - The HTTP status code to categorize.
+ * @returns {HttpResponseType} The categorized response type.
+ */
+const getResType = (code) => {
+  // Informational responses
+  if (codeIs.info(code)) return 'info';
+  // Successful responses
+  if (codeIs.success(code)) return 'success';
+  // Redirection messages
+  if (codeIs.redirect(code)) return 'redirect';
+  // Client error responses
+  if (codeIs.clientError(code)) return 'client-error';
+  // Server error responses
+  if (codeIs.serverError(code)) return 'server-error';
+  // Unknown error
+  return 'unknown';
+};
+
+///////////////////////////////////////////////////////////////////
+
+/**
+ * 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<TinyServiceWorkerEngine, Layer, IdString, VersionString, Options>} SwPluginInstaller
+ */
+
+/**
+ * Represents a plugin instance designed to be integrated into a TinyServiceWorkerEngine.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {TinyPlugin<TinyServiceWorkerEngine, Layer, IdString, VersionString, Options>} TinyServiceWorkerPlugin
+ */
+
+/**
+ * A mock class to simulate NotificationEvent for messaging purposes.
+ * @extends Event
+ */
+class MockNotificationEvent extends Event {
+  /** @type {ExtendableMessageEvent} The wrapped message event. */
+  #event;
+  /**
+   * @type {string}
+   * Required by NotificationEvent interface
+   */
+  #action;
+  /** @type {Notification} The mocked notification instance. */
+  #notification;
+
+  get notification() {
+    return this.#notification;
+  }
+
+  get action() {
+    return this.#action;
+  }
+
+  /**
+   * @param {ExtendableMessageEvent} event - The event.
+   * @param {any} data - Notification details.
+   * @param {string} [action=''] - The action identifier that was clicked.
+   */
+  constructor(event, data, action = '') {
+    super('notificationclick');
+    this.#event = event;
+    this.#action = action;
+    this.#notification = {
+      title: data.title,
+      body: data.body,
+      ...data.options, // Ensures fields like 'date', 'tag' and 'icon' are passed on
+      close: () => {
+        // Mock implementation of the close method
+      },
+    };
+  }
+
+  /**
+   * Mocking waitUntil to satisfy the ExtendableEvent/NotificationEvent interface.
+   * @param {Promise<any>} promise - The promise to keep the event alive.
+   * @returns {void}
+   */
+  waitUntil(promise) {
+    return this.#event.waitUntil(promise);
+  }
+}
+
+/**
+ * Manages the lifecycle and execution of modules based on the provided configuration.
+ */
+class TinyServiceWorkerEngine extends TinyPlugin.TinyPluginCore {
+  static #PUSH_TYPE = utils.PUSH_TYPE;
+  static get PUSH_TYPE() {
+    return TinyServiceWorkerEngine.#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 in the reserved list.
+   */
+  static #validateEventType(type) {
+    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.`,
+      );
+    }
+  }
+
+  /**
+   * A function used to format a reply message into a standard MessagingData object.
+   *
+   * @param {string} type - The type identifier for the reply message.
+   * @param {MessagePayload} [payload] - The payload to be sent in the reply.
+   * @param {boolean} [strict=false] - Whether to enforce the reserved event name rules.
+   * @returns {MessagingData} The formatted message object.
+   * @throws {TypeError} If type is not a string, payload is not a non-null object,
+   *   or strict is not a boolean.
+   */
+  static #replyTemplate(type, payload, strict = false) {
+    if (typeof type !== 'string') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] replyTemplate: type must be a string. Received: ${typeof type}`,
+      );
+    }
+    if (
+      typeof payload !== 'undefined' &&
+      (Array.isArray(payload) || typeof payload !== 'object' || payload === null)
+    ) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] replyTemplate: payload must be a non-null object when provided.',
+      );
+    }
+    if (typeof strict !== 'boolean') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] replyTemplate: strict must be a boolean. Received: ${typeof strict}`,
+      );
+    }
+    if (strict) TinyServiceWorkerEngine.#validateEventType(type);
+    return { type, data: payload };
+  }
+
+  /**
+   * A function used to format a reply message into a standard MessagingData object.
+   *
+   * @param {string} type - The type identifier for the reply message.
+   * @param {MessagePayload} [payload] - The payload to be sent in the reply.
+   * @returns {MessagingData} The formatted message object.
+   * @throws {TypeError} If type is not a string.
+   */
+  static replyTemplate(type, payload) {
+    return TinyServiceWorkerEngine.#replyTemplate(type, payload, true);
+  }
+
+  /**
+   * A function that handles the actual postMessage call to a specific Client.
+   *
+   * @param {Client} targetSource - The target client to receive the message.
+   * @param {string} type - The type identifier for the reply message.
+   * @param {MessagePayload} [payload] - The payload to be sent in the reply.
+   * @returns {void}
+   * @throws {TypeError} If targetSource is invalid or type is not a string.
+   */
+  static #replyTo(targetSource, type, payload, strict = false) {
+    if (!(targetSource instanceof Client)) {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] replyTo: targetSource must be a valid Client with a postMessage method.`,
+      );
+    }
+    if (typeof strict !== 'boolean') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] replyTo: strict must be a boolean. Received: ${typeof strict}`,
+      );
+    }
+    targetSource.postMessage(TinyServiceWorkerEngine.#replyTemplate(type, payload, strict));
+  }
+
+  /**
+   * A function that handles the actual postMessage call to a specific Client.
+   *
+   * @param {Client} targetSource - The target client to receive the message.
+   * @param {string} type - The type identifier for the reply message.
+   * @param {MessagePayload} [payload] - The payload to be sent in the reply.
+   * @returns {void}
+   * @throws {TypeError} If targetSource is invalid or type is not a string.
+   */
+  static replyTo(targetSource, type, payload) {
+    return TinyServiceWorkerEngine.#replyTo(targetSource, type, payload, true);
+  }
+
+  /**
+   * A function that handles the actual postMessage call to all Clients.
+   *
+   * @param {MessageReplyToAllOptions} ops - The options for the reply.
+   * @param {boolean} [strict=false] - Whether to perform strict event type validation.
+   * @returns {Promise<MessageReplyToAllResponse>} The result of the broadcast.
+   * @throws {TypeError} If ops is not a valid object or strict is not a boolean.
+   */
+  static async #replyToAll(ops, strict = false) {
+    if (typeof ops !== 'object' || ops === null || Array.isArray(ops)) {
+      throw new TypeError('[TinyServiceWorkerEngine] replyToAll: ops must be a non-null object.');
+    }
+    if (typeof strict !== 'boolean') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] replyToAll: strict must be a boolean. Received: ${typeof strict}`,
+      );
+    }
+
+    const { type, data, options = { type: 'window', includeUncontrolled: true } } = ops;
+
+    if (typeof type !== 'string' || type.trim() === '') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] replyToAll: ops.type must be a non-empty string.',
+      );
+    }
+    if (
+      typeof data !== 'undefined' &&
+      (Array.isArray(data) || typeof data !== 'object' || data === null)
+    ) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] replyToAll: ops.data must be a non-null object when provided.',
+      );
+    }
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] replyToAll: ops.options must be a non-null object when provided.',
+      );
+    }
+
+    return sw.clients.matchAll(options).then((clientList) =>
+      clientList.forEach((client) => {
+        TinyServiceWorkerEngine.#replyTo(client, type, data, strict);
+      }),
+    );
+  }
+
+  /**
+   * A function that handles the actual postMessage call to all Clients.
+   *
+   * @param {MessageReplyToAllOptions} ops - The options for the reply.
+   * @returns {Promise<MessageReplyToAllResponse>} The result of the broadcast.
+   */
+  static async replyToAll(ops) {
+    return TinyServiceWorkerEngine.#replyToAll(ops, true);
+  }
+
+  /**
+   * Checks if the provided Request object is a navigation request.
+   * @param {Request} req - The request to evaluate.
+   * @returns {boolean} True if the request mode is 'navigate', false otherwise.
+   */
+  static isNavigate(req) {
+    return req.mode === 'navigate';
+  }
+
+  /**
+   * Determines whether the origin of a given Request or URL matches the origin of the current Service Worker context.
+   * @param {Request|URL} data - The request or URL to check.
+   * @returns {boolean} True if the origins match, false otherwise.
+   */
+  static isSameOrigin(data) {
+    // 1. Parse the request URL into a URL object to access its specific components
+    const reqUrl = data instanceof Request ? new URL(data.url) : data;
+
+    // 2. Compare the origin of the request with the origin of the Service Worker itself
+    // self.location.origin provides the protocol, domain, and port of the Service Worker
+    return reqUrl.origin === self.location.origin;
+  }
+
+  /**
+   * Retrieves the configuration for a specific HTTP status code.
+   * @param {number} c - The HTTP status code.
+   * @returns {RouterCodeConfig} The configuration for the given code.
+   * @throws {TypeError} If c is not a number.
+   */
+  getCodeCfg(c) {
+    if (typeof c !== 'number') throw new TypeError('Code must be a number.');
+    /** @type {RouterCodeConfig|undefined} */
+    let routerCodeCfg;
+
+    // 1. Check user-defined codes in the Map
+    routerCodeCfg = this.#config.fetch.router.codes.get(c);
+
+    // 2. If not found, check for dynamic default configurations
+    // @ts-ignore
+    if (!routerCodeCfg) routerCodeCfg = this.#defaultCode[c].data;
+
+    // 3. If still not found, fallback to the 'unknown' configuration
+    if (!routerCodeCfg) {
+      routerCodeCfg = this.createFetchRes({
+        isError: true,
+        msg: this.#globalMsgCode.unknown.msg,
+        logMsg: this.#globalMsgCode.unknown.logMsg,
+        pathGetter: () => this.globalPathGetter(this.#globalMsgCode.unknown.path),
+      });
+    }
+
+    return { ...routerCodeCfg };
+  }
+
+  /**
+   * Sets the SPA mode configuration.
+   * @param {boolean} value - The value to set for spaMode.
+   * @throws {TypeError} If value is not a boolean.
+   */
+  set spaMode(value) {
+    if (typeof value !== 'boolean') {
+      throw new TypeError(`Invalid type for "spaMode": expected boolean, got ${typeof value}`);
+    }
+    this.#config.spaMode = value;
+  }
+
+  /**
+   * Gets the current SPA mode configuration.
+   * @returns {boolean} The current spaMode value.
+   */
+  get spaMode() {
+    return this.#config.spaMode;
+  }
+
+  /**
+   * Gets a deep clone of the current lifecycle configuration.
+   *
+   * @returns {LifecycleOptions} A deep cloned copy of the lifecycle configuration.
+   */
+  get lifecycle() {
+    return TinyCloner.clone(this.#config.lifecycle);
+  }
+
+  /**
+   * Merges the provided properties into the current lifecycle configuration.
+   *
+   * The operation is a **merge**, not a replacement: omitted keys keep their
+   * current value. This is required because the internal validation is strict,
+   * so a partial patch such as `{ strategyOrder: 'before' }` must not erase the
+   * install and activate strategies.
+   *
+   * @param {Partial<LifecycleOptions>} value - The lifecycle properties to merge.
+   * @throws {TypeError} If `value` is not a valid partial {@link LifecycleOptions}.
+   */
+  set lifecycle(value) {
+    TinyServiceWorkerEngine.#assertLifecycle(value);
+    this.#updateConfig({ lifecycle: value });
+  }
+
+  /**
+   * Returns the global path based on the current SPA mode configuration.
+   * @param {string} path - The original path.
+   * @returns {string} The path adjusted for SPA mode or the original path.
+   * @throws {TypeError} If path is not a non-empty string.
+   */
+  globalPathGetter(path) {
+    if (typeof path !== 'string' || path.trim() === '') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] globalPathGetter: path must be a non-empty string.',
+      );
+    }
+    return !this.#config.spaMode ? path : this.#globalMsgCode.spaPath;
+  }
+
+  /** @type {Map<string, ApiHandlerCallback>} The registered API handlers, keyed by call type. */
+  #apiHandlers = new Map();
+
+  /** @type {Map<string, SyncCallback>} The registered sync listeners, keyed by sync tag. */
+  #syncListeners = new Map();
+
+  /** @type {Map<string, LifecycleCallback>} The registered install listeners, keyed by tag. */
+  #installListeners = new Map();
+
+  /** @type {Map<string, LifecycleCallback>} The registered activate listeners, keyed by tag. */
+  #activateListeners = new Map();
+
+  /** @type {Map<string, {resolve: (value: any) => void, reject: (reason: Error) => void, timer: NodeJS.Timeout}>} The in-flight API requests, keyed by correlation id. */
+  #pendingRequests = new Map();
+
+  /** @type {GlobalMsgCode} The active global message table used to build responses. */
+  #globalMsgCode = {
+    spaPath: '/index.html',
+    unknown: {
+      path: '/500.html',
+      msg: 'Unknown',
+      logMsg: 'Unknown route error',
+    },
+    200: {
+      path: null,
+      msg: 'Success',
+      logMsg: 'Valid route',
+    },
+    404: {
+      path: '/404.html',
+      msg: 'Not Found',
+      logMsg: 'Route not found',
+    },
+    500: {
+      path: '/500.html',
+      msg: 'Internal Server Error',
+      logMsg: 'Route server error',
+    },
+  };
+
+  /** @type {{ 200: DefaultCodeData, 404: DefaultCodeData, 500: DefaultCodeData }} The built-in response handlers, keyed by HTTP status code. */
+  #defaultCode = {
+    200: {
+      pathGetter: (path) => this.globalPathGetter(path),
+      data: {
+        fn: (ops) =>
+          this.fetchFn(
+            this.#globalMsgCode[200].msg,
+            this.#globalMsgCode[200].logMsg,
+            this.#defaultCode[200].pathGetter,
+            ops,
+          ),
+        msg: this.#globalMsgCode[200].msg,
+        logMsg: this.#globalMsgCode[200].logMsg,
+      },
+    },
+    404: {
+      pathGetter: () => this.globalPathGetter(this.#globalMsgCode[404].path),
+      data: {
+        fn: (ops) =>
+          this.fetchErrorFn(
+            this.#globalMsgCode[404].msg,
+            this.#globalMsgCode[404].logMsg,
+            this.#defaultCode[404].pathGetter,
+            ops,
+          ),
+        msg: this.#globalMsgCode[404].msg,
+        logMsg: this.#globalMsgCode[404].logMsg,
+      },
+    },
+    500: {
+      pathGetter: () => this.globalPathGetter(this.#globalMsgCode[500].path),
+      data: {
+        fn: (ops) =>
+          this.fetchErrorFn(
+            this.#globalMsgCode[500].msg,
+            this.#globalMsgCode[500].logMsg,
+            this.#defaultCode[500].pathGetter,
+            ops,
+          ),
+        msg: this.#globalMsgCode[500].msg,
+        logMsg: this.#globalMsgCode[500].logMsg,
+      },
+    },
+  };
+
+  /**
+   * Handles a successful fetch request.
+   * @param {string} msg - The message to be logged.
+   * @param {string} logMsg - The log message to be recorded.
+   * @param {string|PathGetter} pathGetter - The path to fetch.
+   * @param {FnOptions} options - The options for the fetch operation.
+   * @returns {Promise<Response>} A promise that resolves to the Response object.
+   */
+  async fetchFn(msg, logMsg, pathGetter, options) {
+    if (typeof msg !== 'string' || typeof logMsg !== 'string') {
+      throw new TypeError('[TinyServiceWorkerEngine] fetchFn: msg and logMsg must be strings.');
+    }
+    if (typeof pathGetter !== 'string' && typeof pathGetter !== 'function') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] fetchFn: pathGetter must be a string or a function.',
+      );
+    }
+    if (typeof options !== 'object' || options === null || !(options.url instanceof URL)) {
+      throw new TypeError('[TinyServiceWorkerEngine] fetchFn: options.url must be a valid URL.');
+    }
+
+    const { url, code, request, customPath } = options;
+    const path =
+      typeof customPath === 'string'
+        ? customPath
+        : typeof pathGetter === 'string'
+          ? pathGetter
+          : pathGetter(url.toString());
+
+    this.log('info', `${code} - ${logMsg}: ${url.pathname}`);
+    try {
+      const res = await fetch(path === url.toString() ? request : path);
+      return res;
+    } catch (err) {
+      return this.getCodeCfg(500).fn(options);
+    }
+  }
+
+  /**
+   * Handles a failed fetch request by simulating an error page.
+   * @param {string} msg - The message to be logged.
+   * @param {string} logMsg - The log message to be recorded.
+   * @param {string|PathGetter} pathGetter - The path to fetch.
+   * @param {FnOptions} options - The options for the fetch operation.
+   * @returns {Promise<Response>} A promise that resolves to the error Response object.
+   */
+  async fetchErrorFn(msg, logMsg, pathGetter, options) {
+    if (typeof msg !== 'string' || typeof logMsg !== 'string') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] fetchErrorFn: msg and logMsg must be strings.',
+      );
+    }
+    if (typeof pathGetter !== 'string' && typeof pathGetter !== 'function') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] fetchErrorFn: pathGetter must be a string or a function.',
+      );
+    }
+    if (typeof options !== 'object' || options === null || !(options.url instanceof URL)) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] fetchErrorFn: options.url must be a valid URL.',
+      );
+    }
+
+    const { url, code, event, request, resType, customMsg, customPath } = options;
+    const path =
+      typeof customPath === 'string'
+        ? customPath
+        : typeof pathGetter === 'string'
+          ? pathGetter
+          : pathGetter(url.toString());
+
+    this.log('warn', `${code} - ${logMsg}: ${url.pathname}`);
+    const errMsg = typeof customMsg === 'string' ? customMsg : msg;
+
+    this.emit('fetchError', {
+      event,
+      request,
+      error: new Error(`${code} ${errMsg}`),
+      url,
+      resType,
+    });
+
+    // Simulating Apache2 ErrorDocument behavior by serving path.html with a status
+    try {
+      const res = await fetch(path);
+      return new Response(res.body, {
+        status: code,
+        statusText: errMsg,
+        headers: res.headers,
+      });
+    } catch {
+      return new Response(this.#globalMsgCode[500].msg, { status: 500 });
+    }
+  }
+
+  /**
+   * Creates a configuration for a fetch response.
+   * @param {Object} ops - The creation options.
+   * @param {boolean} ops.isError - Indicates if it is an error response.
+   * @param {string} ops.msg - The message to be sent.
+   * @param {string} ops.logMsg - The log message.
+   * @param {string|PathGetter} ops.pathGetter - The path to use for the response.
+   * @returns {RouterCodeConfig} The newly created configuration.
+   * @throws {TypeError} If any property is missing or has the wrong type.
+   */
+  createFetchRes({ isError, msg, logMsg, pathGetter }) {
+    if (typeof isError !== 'boolean') {
+      throw new TypeError('[TinyServiceWorkerEngine] createFetchRes: isError must be a boolean.');
+    }
+    if (typeof msg !== 'string') {
+      throw new TypeError('[TinyServiceWorkerEngine] createFetchRes: msg must be a string.');
+    }
+    if (typeof logMsg !== 'string') {
+      throw new TypeError('[TinyServiceWorkerEngine] createFetchRes: logMsg must be a string.');
+    }
+    if (typeof pathGetter !== 'string' && typeof pathGetter !== 'function') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] createFetchRes: pathGetter must be a string or a function.',
+      );
+    }
+
+    return {
+      fn: (ops) =>
+        isError
+          ? this.fetchErrorFn(msg, logMsg, pathGetter, ops)
+          : this.fetchFn(msg, logMsg, pathGetter, ops),
+      msg,
+      logMsg,
+    };
+  }
+
+  /**
+   * The push router. Kept outside `#config` on purpose: `get config()` deep
+   * clones the configuration, and a class instance would not survive the clone.
+   * @type {TinyPushRouter}
+   */
+  #pushRouter = new TinyPushRouter();
+
+  /**
+   * Replaces the push router.
+   * @param {TinyPushRouter} router - The new router.
+   * @throws {TypeError} If `router` is not a TinyPushRouter.
+   */
+  set pushRouter(router) {
+    if (!(router instanceof TinyPushRouter)) {
+      throw new TypeError('[TinyServiceWorkerEngine] pushRouter must be a TinyPushRouter.');
+    }
+    this.#pushRouter = router;
+  }
+
+  /** @returns {TinyPushRouter} The active push router. */
+  get pushRouter() {
+    return this.#pushRouter;
+  }
+
+  /**
+   * The internal configuration state of the engine.
+   * @type {ServiceWorkerSettings}
+   */
+  #config = {
+    spaMode: false,
+    lifecycle: {
+      installStrategy: 'immediate',
+      activateStrategy: 'immediate',
+      installOrder: 'after',
+      activateOrder: 'after',
+    },
+    push: {
+      enabled: true,
+      vapidPublicKey: '',
+      subscribeEndpoint: '',
+      defaultIcon: '/icons/notification-192.png',
+      defaultBadge: '/icons/badge-72.png',
+      defaultUrl: '/',
+    },
+    sync: {
+      enabled: true,
+    },
+    fetch: {
+      enabled: true,
+      router: {
+        enabled: false,
+        codes: new Map(),
+      },
+    },
+    messaging: {
+      enabled: true,
+    },
+  };
+
+  /**
+   * Sets the engine configuration.
+   * @param {ServiceWorkerSettings} config - The new configuration to apply.
+   * @throws {TypeError} If the configuration does not meet the minimum requirements.
+   */
+  set config(config) {
+    this.#updateConfig(config, true);
+  }
+
+  /**
+   * Gets the current engine configuration.
+   * Returns a deep clone to prevent external mutation of the internal state.
+   * @returns {ServiceWorkerSettings} A deep cloned copy of the configuration.
+   */
+  get config() {
+    return TinyCloner.clone(this.#config);
+  }
+
+  /**
+   * A map containing registered message type listeners.
+   * @type {Map<string, MessageCallback>}
+   */
+  #messages = new Map();
+
+  /**
+   * A set of event names that must be ignored when received from the browser.
+   * Useful to avoid collisions with third-party Service Workers that share the same scope.
+   * @type {Set<string>}
+   */
+  #eventBlacklist = new Set();
+
+  /**
+   * A map containing registered fetch RegExp listeners.
+   * @type {Map<string, FetchCallback>}
+   */
+  #fetchRegExp = new Map();
+
+  /**
+   * A map containing registered fetch URL listeners.
+   * @type {Map<string, FetchCallback>}
+   */
+  #fetchUrls = new Map();
+
+  /**
+   * A map containing the global fetch tracking listeners.
+   * @type {Map<string, FetchCallback>}
+   */
+  #fetchGlobal = new Map();
+
+  /**
+   * Flag indicating if the engine has been initialized.
+   * @type {boolean}
+   */
+  #started = false;
+
+  /**
+   * Indicates if the engine has been initialized.
+   * @returns {boolean} True if started, false otherwise.
+   */
+  get started() {
+    return this.#started;
+  }
+
+  /**
+   * Performs rigorous deep validation of the configuration object.
+   * @param {ServiceWorkerSettings | Partial<PartialServiceWorkerSettings>} config - The configuration object to validate.
+   * @param {boolean} [strict=false] - If true, ensures all properties defined in the typedef are present.
+   * @throws {TypeError} If any property is of the wrong type or is missing when in strict mode.
+   */
+  #validateConfig(config, strict = false) {
+    if (typeof config !== 'object' || config === null) {
+      throw new TypeError('Configuration must be a non-null object.');
+    }
+
+    /**
+     * Helper to validate existence and type.
+     * @template {Record<any, any>} T
+     * @param {T} obj - The object containing the property.
+     * @param {string} key - The property name.
+     * @param {string} type - The expected typeof result.
+     * @param {string} context - Context for the error message.
+     */
+    const validateField = (obj, key, type, context) => {
+      const value = obj[key];
+      if (strict && value === undefined) {
+        throw new TypeError(`Missing required property: "${context}.${key}"`);
+      }
+      if (value !== undefined && typeof value !== type) {
+        throw new TypeError(
+          `Invalid type for "${context}.${key}": expected ${type}, got ${typeof value}`,
+        );
+      }
+    };
+
+    validateField(config, 'spaMode', 'boolean', 'root');
+
+    // Deep validation for 'fetch' configuration
+    if (config.fetch !== undefined) {
+      if (typeof config.fetch !== 'object' || config.fetch === null) {
+        throw new TypeError('Fetch configuration must be a non-null object.');
+      }
+      validateField(config.fetch, 'enabled', 'boolean', 'fetch');
+
+      if (config.fetch.router !== undefined) {
+        if (typeof config.fetch.router !== 'object' || config.fetch.router === null) {
+          throw new TypeError('Fetch router configuration must be a non-null object.');
+        }
+        validateField(config.fetch.router, 'enabled', 'boolean', 'fetch.router');
+
+        // Deep validation for 'router.codes' Map
+        if (config.fetch.router.codes !== undefined) {
+          if (!(config.fetch.router.codes instanceof Map)) {
+            throw new TypeError(
+              '[TinyServiceWorkerEngine] validateConfig: fetch.router.codes must be a Map.',
+            );
+          }
+
+          for (const [code, cfg] of config.fetch.router.codes.entries()) {
+            // Validate Map Key
+            if (typeof code !== 'number') {
+              throw new TypeError(
+                `[TinyServiceWorkerEngine] validateConfig: Map key must be a number. Received: ${typeof code}`,
+              );
+            }
+
+            // Validate Map Value (RouterCodeConfig)
+            if (typeof cfg !== 'object' || cfg === null) {
+              throw new TypeError(
+                `[TinyServiceWorkerEngine] validateConfig: Value for code ${code} must be an object.`,
+              );
+            }
+
+            if (typeof cfg.fn !== 'function') {
+              throw new TypeError(
+                `[TinyServiceWorkerEngine] validateConfig: cfg.fn for code ${code} must be a function.`,
+              );
+            }
+            if (typeof cfg.msg !== 'string') {
+              throw new TypeError(
+                `[TinyServiceWorkerEngine] validateConfig: cfg.msg for code ${code} must be a string.`,
+              );
+            }
+            if (typeof cfg.logMsg !== 'string') {
+              throw new TypeError(
+                `[TinyServiceWorkerEngine] validateConfig: cfg.logMsg for code ${code} must be a string.`,
+              );
+            }
+          }
+        } else if (strict) {
+          throw new TypeError('Missing required property: "fetch.router.codes"');
+        }
+      } else if (strict) {
+        throw new TypeError('Missing required property: "fetch.router"');
+      }
+    } else if (strict) {
+      throw new TypeError('Missing required property: "fetch"');
+    }
+
+    if (config.lifecycle !== undefined) {
+      TinyServiceWorkerEngine.#assertLifecycle(config.lifecycle);
+
+      if (strict) {
+        for (const [key] of LIFECYCLE_SPEC) {
+          if (/** @type {Record<string, unknown>} */ (config.lifecycle)[key] === undefined) {
+            throw new TypeError(`Missing required property: "lifecycle.${key}"`);
+          }
+        }
+      }
+    } else if (strict) {
+      throw new TypeError('Missing required property: "lifecycle"');
+    }
+
+    if (config.sync !== undefined) {
+      if (typeof config.sync !== 'object' || config.sync === null) {
+        throw new TypeError('Sync configuration must be a non-null object.');
+      }
+      validateField(config.sync, 'enabled', 'boolean', 'sync');
+    } else if (strict) {
+      throw new TypeError('Missing required property: "sync"');
+    }
+
+    // Deep validation for 'messaging' configuration
+    if (config.messaging !== undefined) {
+      if (typeof config.messaging !== 'object' || config.messaging === null) {
+        throw new TypeError('Messaging configuration must be a non-null object.');
+      }
+      validateField(config.messaging, 'enabled', 'boolean', 'messaging');
+    } else if (strict) {
+      throw new TypeError('Missing required property: "messaging"');
+    }
+  }
+
+  /**
+   * Updates the internal configuration.
+   * @param {Partial<PartialServiceWorkerSettings>} config - The partial configuration to apply.
+   * @param {boolean} [forceFullValidation=false] - Whether to force full validation.
+   */
+  #updateConfig(config, forceFullValidation = false) {
+    this.#validateConfig(config, forceFullValidation);
+
+    // 1. Prepare Messaging configuration
+    const newMessaging = config.messaging
+      ? { ...this.#config.messaging, ...config.messaging }
+      : this.#config.messaging;
+
+    // 2. Prepare Fetch Router configuration
+    let newRouter = this.#config.fetch.router;
+    if (config.fetch?.router) {
+      // Merge the router properties
+      newRouter = {
+        ...this.#config.fetch.router,
+        ...config.fetch.router,
+      };
+
+      // If the router contains a Map of codes, create a deep clone of the Map and its values
+      if (newRouter.codes instanceof Map) {
+        newRouter.codes = new Map(
+          Array.from(newRouter.codes, ([code, cfg]) => [
+            code,
+            { ...cfg }, // Clone of the RouterCodeConfig object
+          ]),
+        );
+      }
+    }
+
+    // 3. Prepare Fetch configuration
+    const newFetch = config.fetch
+      ? {
+          ...this.#config.fetch,
+          ...config.fetch,
+          router: newRouter,
+        }
+      : this.#config.fetch;
+
+    // 4. Prepare Fetch configuration
+    const newPush = config.push
+      ? {
+          ...this.#config.push,
+          ...config.push,
+        }
+      : this.#config.push;
+
+    // 5. Prepare Lifecycle configuration
+    const newLifecycle = config.lifecycle
+      ? { ...this.#config.lifecycle, ...config.lifecycle }
+      : this.#config.lifecycle;
+
+    // 6. Prepare Sync configuration
+    const newSync = config.sync ? { ...this.#config.sync, ...config.sync } : this.#config.sync;
+
+    // 7. Apply to the instance's private state
+    this.#config = {
+      spaMode: config.spaMode ?? this.#config.spaMode,
+      lifecycle: newLifecycle,
+      fetch: newFetch,
+      push: newPush,
+      sync: newSync,
+      messaging: newMessaging,
+    };
+
+    // Final validation to ensure the merge did not break type rules
+    this.#validateConfig(this.#config, true);
+  }
+
+  /**
+   * Initializes a new instance of the TinyServiceWorkerEngine with the provided configuration and logger settings.
+   * @param {Partial<PartialServiceWorkerSettings>} config - The configuration to apply.
+   * @param {Object} [lgConfig] - Configuration options for the instance.
+   * @param {boolean} [lgConfig.debugMode=false] - Whether to enable internal debug logging.
+   * @param {boolean} [lgConfig.useLogColors=false] - Whether to enable log color support.
+   * @param {Partial<Console>} [lgConfig.logger=console] - A custom logger object.
+   * @throws {TypeError} If the configuration does not meet the minimum requirements.
+   */
+  constructor(config = {}, lgConfig = {}) {
+    super({
+      logCfg: {
+        id: '[_main_class_TinySW-Engine_reset_]',
+        logger: lgConfig.logger ?? console,
+        debugMode: lgConfig.debugMode ?? false,
+        useLogColors: lgConfig.useLogColors ?? false,
+      },
+    });
+    this.#updateConfig(config);
+  }
+
+  /**
+   * Validates that a listener identifier is a non-empty string.
+   * @param {unknown} type - The value to validate.
+   * @param {string} context - The method name used in the error message.
+   * @returns {void}
+   * @throws {TypeError} If type is not a non-empty string.
+   */
+  static #assertListenerType(type, context) {
+    if (typeof type !== 'string' || type.trim() === '') {
+      throw new TypeError(`[TinyServiceWorkerEngine] ${context}: type must be a non-empty string.`);
+    }
+  }
+
+  /**
+   * Validates that a listener callback is a function.
+   * @param {unknown} callback - The value to validate.
+   * @param {string} context - The method name used in the error message.
+   * @returns {void}
+   * @throws {TypeError} If callback is not a function.
+   */
+  static #assertListenerCallback(callback, context) {
+    if (typeof callback !== 'function') {
+      throw new TypeError(`[TinyServiceWorkerEngine] ${context}: callback must be a function.`);
+    }
+  }
+
+  /**
+   * Gets the number of registered fetch RegExp listeners.
+   * @returns {number} The count of registered RegExp listeners.
+   */
+  get fetchRegExpSize() {
+    return this.#fetchRegExp.size;
+  }
+
+  /**
+   * Adds a fetch RegExp listener.
+   * @param {string} type - The identifier for the fetch type.
+   * @param {FetchCallback} callback - The callback to execute.
+   */
+  addFetchRegExpListener(type, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'addFetchRegExpListener');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'addFetchRegExpListener');
+    this.#fetchRegExp.set(type, callback);
+  }
+
+  /**
+   * Removes a fetch RegExp listener.
+   * @param {string} type - The identifier for the fetch type.
+   * @returns {boolean} True if the listener was removed, false otherwise.
+   */
+  removeFetchRegExpListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'removeFetchRegExpListener');
+    return this.#fetchRegExp.delete(type);
+  }
+
+  /**
+   * Retrieves a fetch RegExp listener.
+   * @param {string} type - The identifier for the fetch type.
+   * @returns {FetchCallback|undefined} The listener, or undefined if not found.
+   */
+  getFetchRegExpListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'getFetchRegExpListener');
+    return this.#fetchRegExp.get(type);
+  }
+
+  /**
+   * Checks if a fetch RegExp listener exists.
+   * @param {string} type - The identifier for the fetch type.
+   * @returns {boolean} True if the listener exists, false otherwise.
+   */
+  hasFetchRegExp(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'hasFetchRegExp');
+    return this.#fetchRegExp.has(type);
+  }
+
+  /**
+   * Clears all registered fetch RegExp listeners.
+   * @returns {void}
+   */
+  clearFetchRegExps() {
+    return this.#fetchRegExp.clear();
+  }
+
+  /**
+   * Gets the number of registered fetch URL listeners.
+   * @returns {number} The count of registered URL listeners.
+   */
+  get fetchUrlSize() {
+    return this.#fetchUrls.size;
+  }
+
+  /**
+   * Adds a fetch URL listener.
+   * @param {string} type - The identifier for the fetch type.
+   * @param {FetchCallback} callback - The callback to execute.
+   */
+  addFetchUrlListener(type, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'addFetchUrlListener');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'addFetchUrlListener');
+    this.#fetchUrls.set(type, callback);
+  }
+
+  /**
+   * Removes a fetch URL listener.
+   * @param {string} type - The identifier for the fetch type.
+   * @returns {boolean} True if the listener was removed, false otherwise.
+   */
+  removeFetchUrlListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'removeFetchUrlListener');
+    return this.#fetchUrls.delete(type);
+  }
+
+  /**
+   * Retrieves a fetch URL listener.
+   * @param {string} type - The identifier for the fetch type.
+   * @returns {FetchCallback|undefined} The listener, or undefined if not found.
+   */
+  getFetchUrlListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'getFetchUrlListener');
+    return this.#fetchUrls.get(type);
+  }
+
+  /**
+   * Checks if a fetch URL listener exists.
+   * @param {string} type - The identifier for the fetch type.
+   * @returns {boolean} True if the listener exists, false otherwise.
+   */
+  hasFetchUrl(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'hasFetchUrl');
+    return this.#fetchUrls.has(type);
+  }
+
+  /**
+   * Clears all registered fetch URL listeners.
+   * @returns {void}
+   */
+  clearFetchUrls() {
+    return this.#fetchUrls.clear();
+  }
+
+  /**
+   * Gets the number of registered global fetch tracking listeners.
+   * @returns {number} The count of registered tracking listeners.
+   */
+  get fetchGlobalSize() {
+    return this.#fetchGlobal.size;
+  }
+
+  /**
+   * Adds a global fetch tracking listener.
+   * @param {string} type - The identifier for the tracking type.
+   * @param {FetchCallback} callback - The callback function to be executed.
+   */
+  addFetchGlobalListener(type, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'addFetchGlobalListener');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'addFetchGlobalListener');
+    this.#fetchGlobal.set(type, callback);
+  }
+
+  /**
+   * Removes a global fetch tracking listener.
+   * @param {string} type - The identifier for the tracking type.
+   * @returns {boolean} True if the listener was removed, false otherwise.
+   */
+  removeFetchGlobalListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'removeFetchGlobalListener');
+    return this.#fetchGlobal.delete(type);
+  }
+
+  /**
+   * Retrieves a global fetch tracking listener.
+   * @param {string} type - The identifier for the tracking type.
+   * @returns {FetchCallback|undefined} The listener, or undefined if not found.
+   */
+  getFetchGlobalListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'getFetchGlobalListener');
+    return this.#fetchGlobal.get(type);
+  }
+
+  /**
+   * Checks if a global fetch tracking listener exists.
+   * @param {string} type - The identifier for the tracking type.
+   * @returns {boolean} True if the listener exists, false otherwise.
+   */
+  hasFetchGlobal(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'hasFetchGlobal');
+    return this.#fetchGlobal.has(type);
+  }
+
+  /**
+   * Clears all global fetch tracking listeners.
+   * @returns {void}
+   */
+  clearFetchGlobals() {
+    return this.#fetchGlobal.clear();
+  }
+
+  /**
+   * Gets the number of registered message listeners.
+   * @returns {number} The count of registered message listeners.
+   */
+  get messagesSize() {
+    return this.#messages.size;
+  }
+
+  /**
+   * Adds a message listener.
+   * @param {string} type - The identifier for the message type.
+   * @param {MessageCallback} callback - The callback to execute.
+   */
+  addMessageListener(type, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'addMessageListener');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'addMessageListener');
+    this.#messages.set(type, callback);
+  }
+
+  /**
+   * Removes a message listener.
+   * @param {string} type - The identifier for the message type.
+   * @returns {boolean} True if the listener was removed, false otherwise.
+   */
+  removeMessageListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'removeMessageListener');
+    return this.#messages.delete(type);
+  }
+
+  /**
+   * Retrieves a message listener.
+   * @param {string} type - The identifier for the message type.
+   * @returns {MessageCallback|undefined} The listener, or undefined if not found.
+   */
+  getMessageListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'getMessageListener');
+    return this.#messages.get(type);
+  }
+
+  /**
+   * Checks if a message listener exists.
+   * @param {string} type - The identifier for the message type.
+   * @returns {boolean} True if the listener exists, false otherwise.
+   */
+  hasMessageListener(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'hasMessageListener');
+    return this.#messages.has(type);
+  }
+
+  /**
+   * Clears all registered message listeners.
+   * @returns {void}
+   */
+  clearMessageListeners() {
+    return this.#messages.clear();
+  }
+
+  /**
+   * Returns a copy of the blacklisted event names.
+   * @returns {string[]} An array with every blacklisted event name.
+   */
+  get eventBlacklist() {
+    return Array.from(this.#eventBlacklist);
+  }
+
+  /**
+   * Adds an event name to the blacklist. Blacklisted events are ignored when
+   * they arrive from the browser.
+   * @param {string} type - The event name to ignore.
+   * @returns {void}
+   * @throws {TypeError} If the type is not a non-empty string.
+   */
+  addToEventBlacklist(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'addToEventBlacklist');
+    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) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'removeFromEventBlacklist');
+    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) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'hasInEventBlacklist');
+    return this.#eventBlacklist.has(type);
+  }
+
+  /**
+   * Removes every event name from the blacklist.
+   * @returns {void}
+   */
+  clearEventBlacklist() {
+    this.#eventBlacklist.clear();
+  }
+
+  /**
+   * Promotes the waiting Service Worker to the active state.
+   *
+   * This is the manual counterpart of the `'immediate'` install strategy. It is
+   * safe to call at any time: when no worker is waiting, the browser resolves the
+   * call without side effects.
+   *
+   * @param {ExtendableEvent} [event] - The lifecycle event that triggered the call, when any.
+   * @returns {Promise<boolean>} `true` when `skipWaiting()` was requested.
+   * @throws {TypeError} If `event` is provided and does not expose a `waitUntil` method.
+   */
+  async skipWaiting(event) {
+    if (!(event instanceof ExtendableEvent)) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] skipWaiting: event must be an ExtendableEvent when provided.',
+      );
+    }
+
+    this.emit('beforeSkipWaiting', { event });
+    await sw.skipWaiting();
+    this.emit('afterSkipWaiting', { event });
+    this.log('info', 'skipWaiting: activation requested.');
+    return true;
+  }
+
+  /**
+   * Makes the active Service Worker take control of every open client.
+   *
+   * This is the manual counterpart of the `'immediate'` activate strategy.
+   *
+   * @param {ClientQueryOptions} [query] - Filter applied to the clients that must be claimed.
+   * @returns {Promise<readonly Client[]>} The clients that are now controlled.
+   * @throws {TypeError} If `query` is provided and is not a non-null object.
+   */
+  async claimClients(query = { type: 'window', includeUncontrolled: true }) {
+    if (typeof query !== 'object' || query === null || Array.isArray(query)) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] claimClients: query must be a non-null object when provided.',
+      );
+    }
+
+    this.emit('beforeClaim', { query });
+    await sw.clients.claim();
+    const clients = await sw.clients.matchAll(query);
+    this.emit('afterClaim', { query, clients });
+    this.log('info', `claimClients: ${clients.length} client(s) claimed.`);
+    return clients;
+  }
+
+  /**
+   * Forces every controlled client to navigate to the given URL.
+   *
+   * Useful when the new Service Worker changes the routing contract and the open
+   * tabs must be reloaded to stay consistent with the new version.
+   *
+   * @param {string} [url] - Target URL. Defaults to the current URL of each client.
+   * @returns {Promise<number>} The number of clients that were navigated.
+   * @throws {TypeError} If `url` is provided and is not a non-empty string.
+   */
+  async reloadClients(url) {
+    if (url !== undefined && (typeof url !== 'string' || url.trim() === '')) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] reloadClients: url must be a non-empty string when provided.',
+      );
+    }
+
+    const clientList = await sw.clients.matchAll({ type: 'window', includeUncontrolled: false });
+    let total = 0;
+
+    for (const client of clientList) {
+      if (typeof client.navigate !== 'function') continue;
+      await client.navigate(url ?? client.url);
+      total += 1;
+    }
+
+    this.log('info', `reloadClients: ${total} client(s) navigated.`);
+    return total;
+  }
+
+  /**
+   * Describes every key accepted by {@link GlobalMsgCode}, except `spaPath`.
+   *
+   * @type {Readonly<Record<string, { nullablePath: boolean }>>}
+   */
+  static #GLOBAL_MSG_CODE_SPEC = Object.freeze({
+    unknown: { nullablePath: false },
+    200: { nullablePath: true },
+    404: { nullablePath: false },
+    500: { nullablePath: false },
+  });
+
+  /**
+   * Validates a single entry of the {@link GlobalMsgCode} table.
+   *
+   * @param {unknown} item - The value to validate.
+   * @param {string} context - Dotted path of the entry, used in the error messages.
+   * @param {boolean} nullablePath - `true` when `path` is allowed to be `null`.
+   * @returns {void}
+   * @throws {TypeError} If `item` is not a valid {@link GlobalMsgCodeItem}.
+   */
+  static #validateGlobalMsgCodeItem(item, context, nullablePath) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] globalMsgCode: "${context}" must be a non-null object.`,
+      );
+    }
+
+    const { path, msg, logMsg } = /** @type {GlobalMsgCodeItem<string|null>} */ (item);
+
+    if (path === null && !nullablePath) {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] globalMsgCode: "${context}.path" must be a non-empty string.`,
+      );
+    }
+
+    if (path !== null && (typeof path !== 'string' || path.trim() === '')) {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] globalMsgCode: "${context}.path" must be a non-empty string${
+          nullablePath ? ' or null' : ''
+        }.`,
+      );
+    }
+
+    if (typeof msg !== 'string' || msg.trim() === '') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] globalMsgCode: "${context}.msg" must be a non-empty string.`,
+      );
+    }
+
+    if (typeof logMsg !== 'string' || logMsg.trim() === '') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] globalMsgCode: "${context}.logMsg" must be a non-empty string.`,
+      );
+    }
+  }
+
+  /**
+   * Performs a deep validation of a {@link GlobalMsgCode} object.
+   *
+   * @param {unknown} config - The value to validate.
+   * @param {boolean} [strict=false] - When `true`, every key of {@link GlobalMsgCode}
+   *   must be present. When `false`, only the provided keys are validated.
+   * @returns {void}
+   * @throws {TypeError} If `config` is not a non-null object, if it contains an
+   *   unknown key, or if one of its entries is not a valid {@link GlobalMsgCodeItem}.
+   */
+  static #validateGlobalMsgCode(config, strict = false) {
+    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+      throw new TypeError('[TinyServiceWorkerEngine] globalMsgCode must be a non-null object.');
+    }
+
+    const allowedKeys = ['spaPath', ...Object.keys(TinyServiceWorkerEngine.#GLOBAL_MSG_CODE_SPEC)];
+    const providedKeys = new Set(Object.keys(config));
+
+    if (strict) {
+      const missingKeys = allowedKeys.filter((key) => !providedKeys.has(key));
+      if (missingKeys.length > 0) {
+        throw new TypeError(
+          `[TinyServiceWorkerEngine] globalMsgCode: missing required key(s): ${missingKeys
+            .map((key) => `"${key}"`)
+            .join(', ')}.`,
+        );
+      }
+    }
+
+    for (const key of providedKeys) {
+      if (!allowedKeys.includes(key)) {
+        throw new TypeError(
+          `[TinyServiceWorkerEngine] globalMsgCode: unknown key "${key}". Expected one of: ${allowedKeys
+            .map((allowed) => `"${allowed}"`)
+            .join(', ')}.`,
+        );
+      }
+
+      if (key === 'spaPath') {
+        const { spaPath } = /** @type {Record<string, unknown>} */ (config);
+        if (typeof spaPath !== 'string' || spaPath.trim() === '') {
+          throw new TypeError(
+            '[TinyServiceWorkerEngine] globalMsgCode: "spaPath" must be a non-empty string.',
+          );
+        }
+        continue;
+      }
+
+      const spec = TinyServiceWorkerEngine.#GLOBAL_MSG_CODE_SPEC[key];
+      TinyServiceWorkerEngine.#validateGlobalMsgCodeItem(
+        /** @type {Record<string, unknown>} */ (config)[key],
+        key,
+        spec.nullablePath,
+      );
+    }
+  }
+
+  /**
+   * Validates a partial lifecycle configuration.
+   *
+   * Only the provided keys are checked, so the method accepts both a full
+   * {@link LifecycleOptions} object and a partial patch.
+   *
+   * @param {unknown} lifecycle - The value to validate.
+   * @returns {void}
+   * @throws {TypeError} If `lifecycle` is not a non-null object, if it contains an
+   *   unknown key, or if one of its values is not an accepted strategy.
+   */
+  static #assertLifecycle(lifecycle) {
+    if (typeof lifecycle !== 'object' || lifecycle === null || Array.isArray(lifecycle)) {
+      throw new TypeError('[TinyServiceWorkerEngine] lifecycle must be a non-null object.');
+    }
+
+    const source = /** @type {Record<string, unknown>} */ (lifecycle);
+
+    for (const key of Object.keys(source)) {
+      if (!LIFECYCLE_SPEC.some(([name]) => name === key)) {
+        throw new TypeError(
+          `[TinyServiceWorkerEngine] lifecycle: unknown key "${key}". Expected one of: ${LIFECYCLE_SPEC.map(
+            ([name]) => `"${name}"`,
+          ).join(', ')}.`,
+        );
+      }
+    }
+
+    for (const [key, allowed] of LIFECYCLE_SPEC) {
+      const value = source[key];
+      if (value !== undefined && !allowed.includes(/** @type {string} */ (value))) {
+        throw new TypeError(
+          `[TinyServiceWorkerEngine] lifecycle.${key} must be one of ${allowed.join(
+            ', ',
+          )}. Received: ${String(value)}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Gets a deep clone of the current global message configuration.
+   * @returns {GlobalMsgCode} A deep cloned copy of the global message configuration.
+   */
+  get globalMsgCode() {
+    return TinyCloner.clone(this.#globalMsgCode);
+  }
+
+  /**
+   * Replaces the whole global message configuration.
+   *
+   * The provided object is validated and deep cloned, so later mutations of the
+   * argument do not affect the engine.
+   *
+   * @param {GlobalMsgCode} newConfig - The complete configuration that replaces the current one.
+   * @throws {TypeError} If `newConfig` is not a complete, valid {@link GlobalMsgCode} object.
+   */
+  set globalMsgCode(newConfig) {
+    TinyServiceWorkerEngine.#validateGlobalMsgCode(newConfig, true);
+    // Merge and then deep clone the result to ensure the internal state is isolated
+    this.#globalMsgCode = TinyCloner.clone(newConfig);
+  }
+
+  /**
+   * Merges the provided properties into the current global message configuration.
+   *
+   * @param {Partial<GlobalMsgCode>} newConfig - The properties to merge.
+   * @throws {TypeError} If `newConfig` is not a valid partial {@link GlobalMsgCode} object.
+   */
+  updateGlobalMsgCode(newConfig) {
+    TinyServiceWorkerEngine.#validateGlobalMsgCode(newConfig, false);
+    // Merge and then deep clone the result to ensure the internal state is isolated
+    this.#globalMsgCode = TinyCloner.clone({ ...this.#globalMsgCode, ...newConfig });
+  }
+
+  /**
+   * Adds or updates a custom router configuration for a specific HTTP status code.
+   * @param {number} code - The HTTP status code.
+   * @param {RouterCodeConfig} config - The configuration object.
+   * @throws {TypeError} If code is not a number or config is invalid.
+   */
+  addRouterCode(code, config) {
+    if (typeof code !== 'number') throw new TypeError('Code must be a number.');
+    if (typeof config !== 'object' || config === null)
+      throw new TypeError('Config must be an object.');
+    if (
+      typeof config.fn !== 'function' ||
+      typeof config.msg !== 'string' ||
+      typeof config.logMsg !== 'string'
+    ) {
+      throw new TypeError(
+        'Invalid RouterCodeConfig: fn must be a function, and msg/logMsg must be strings.',
+      );
+    }
+
+    const newCodes = new Map(this.#config.fetch.router.codes);
+    // Deep clone the incoming config before storing it in the Map
+    newCodes.set(code, TinyCloner.clone(config));
+
+    this.#updateConfig({
+      fetch: {
+        router: {
+          codes: newCodes,
+        },
+      },
+    });
+  }
+
+  /**
+   * Removes a custom router configuration for a specific HTTP status code.
+   * @param {number} code - The HTTP status code to remove.
+   * @returns {boolean} True if a code was removed, false otherwise.
+   * @throws {TypeError} If code is not a number.
+   */
+  removeRouterCode(code) {
+    if (typeof code !== 'number') {
+      throw new TypeError('[TinyServiceWorkerEngine] removeRouterCode: code must be a number.');
+    }
+    const newCodes = new Map(this.#config.fetch.router.codes);
+    if (newCodes.delete(code)) {
+      this.#updateConfig({ fetch: { router: { codes: newCodes } } });
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Retrieves a deep clone of the current configuration for a specific HTTP status code.
+   * @param {number} code - The HTTP status code.
+   * @returns {RouterCodeConfig|undefined} A deep cloned copy of the configuration or undefined.
+   * @throws {TypeError} If code is not a number.
+   */
+  getRouterCode(code) {
+    if (typeof code !== 'number') {
+      throw new TypeError('[TinyServiceWorkerEngine] getRouterCode: code must be a number.');
+    }
+    const cfg = this.#config.fetch.router.codes.get(code);
+    // Return a deep clone to prevent the consumer from mutating the engine's internal Map
+    return cfg ? TinyCloner.clone(cfg) : undefined;
+  }
+
+  /**
+   * Performs checks against registered fetchUrls and fetchRegExp to determine if a request should be intercepted.
+   *
+   * @param {FetchEvent} event - The original fetch event.
+   * @param {URL} url - The parsed URL of the request.
+   * @returns {Promise<FetchCheckerResult>} A promise that resolves to true if the request should proceed normally, or false if it was handled by a plugin.
+   */
+  async #fetchChecker(event, url) {
+    /** @type {Request} */
+    const request = event.request;
+    const isSameOrigin = TinyServiceWorkerEngine.isSameOrigin(request);
+
+    /** @type {FetchCheckerResult} */
+    const result = { code: 404, needValidation: isSameOrigin, continueCheck: true };
+
+    /** @type {FetchObj} */
+    const fetchObj = {
+      isSameOrigin,
+      event,
+      request,
+      url,
+      params: {},
+      replyTemplate: TinyServiceWorkerEngine.replyTemplate,
+      replyTo: TinyServiceWorkerEngine.replyTo,
+      replyToAll: TinyServiceWorkerEngine.replyToAll,
+    };
+
+    // 0. Global Tracking Layer (Always executed, regardless of URL or Router)
+    for (const callback of this.#fetchGlobal.values()) {
+      if (!result.continueCheck) break;
+      try {
+        // Execute the callback. If it returns false, the request is considered "handled"
+        // but since this is a tracking layer, the flow continues according to the router logic.
+        await callback(fetchObj, result);
+      } catch (error) {
+        this.log('error', 'Error in global fetch tracking listener:', error);
+        this.emit('fetchGlobalError', { error, fetchObj });
+      }
+    }
+
+    if (result.continueCheck) {
+      // 3. Execute the plugin if a match is found
+      /** @param {FetchCallback} callback */
+      const executeCallback = async (callback) => {
+        try {
+          this.emit('beforeFetchPlugin', fetchObj);
+          await callback(fetchObj, result);
+          this.emit('afterFetchPlugin', fetchObj);
+        } catch (error) {
+          result.code = 500;
+          fetchObj.error = error instanceof Error ? error : new Error('Unknown Error.');
+          result.continueCheck = false;
+          result.needValidation = true;
+          this.log('error', `Error executing fetch plugin for "${url.pathname}":`, error);
+          this.emit('fetchPluginError', fetchObj);
+        }
+      };
+
+      // 1. Check in fetchUrls (Exact match and Parameterized match)
+      for (const [pattern, callback] of this.#fetchUrls.entries()) {
+        if (!result.continueCheck) break;
+        // Dynamic parameter matching (e.g., /user/:id)
+        if (pattern.includes('/:')) {
+          // Converts the key pattern into the extraction Regex
+          const seg = SegmentExtractor.segmentExtractorV1(pattern);
+          const { match, params } = seg.exec(url.pathname);
+          fetchObj.params = { ...fetchObj.params, ...params };
+          if (match) {
+            await executeCallback(callback);
+            continue; // Route type detected
+          }
+        }
+
+        // Exact match
+        if (url.pathname === pattern) {
+          await executeCallback(callback);
+        }
+      }
+
+      // 2. Check in fetchRegExp
+      for (const [regExpStr, callback] of this.#fetchRegExp.entries()) {
+        if (!result.continueCheck) break;
+        const regex = new RegExp(regExpStr);
+        if (regex.test(url.pathname)) {
+          await executeCallback(callback);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Adds a handler for a specific sync event.
+   * @param {string} tag - The tag of the sync event.
+   * @param {SyncCallback} callback - The function to be executed.
+   * @throws {TypeError} If tag is not a string or callback is not a function.
+   */
+  addSyncListener(tag, callback) {
+    if (typeof tag !== 'string' || tag.trim() === '') {
+      throw new TypeError('Tag must be a non-empty string.');
+    }
+    if (typeof callback !== 'function') {
+      throw new TypeError('Callback must be a function.');
+    }
+    this.#syncListeners.set(tag, callback);
+  }
+
+  /**
+   * Removes a sync handler for a specific tag.
+   * @param {string} tag - The tag of the sync event.
+   * @returns {boolean} True if the handler was removed.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  removeSyncListener(tag) {
+    if (typeof tag !== 'string' || tag.trim() === '') {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] removeSyncListener: tag must be a non-empty string.',
+      );
+    }
+    return this.#syncListeners.delete(tag);
+  }
+
+  /**
+   * Returns the number of registered sync listeners.
+   * @returns {number} The count of registered sync listeners.
+   */
+  get syncListenerSize() {
+    return this.#syncListeners.size;
+  }
+
+  /**
+   * Clears all sync listeners.
+   * @returns {void}
+   */
+  clearSyncListeners() {
+    return this.#syncListeners.clear();
+  }
+
+  /**
+   * Gets the number of registered install listeners.
+   * @returns {number} The count of registered install listeners.
+   */
+  get installListenerSize() {
+    return this.#installListeners.size;
+  }
+
+  /**
+   * Adds an install listener.
+   * @param {string} tag - The identifier for the install listener.
+   * @param {LifecycleCallback} callback - The callback to execute.
+   * @returns {void}
+   * @throws {TypeError} If tag is not a non-empty string or callback is not a function.
+   */
+  addInstallListener(tag, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'addInstallListener');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'addInstallListener');
+    this.#installListeners.set(tag, callback);
+  }
+
+  /**
+   * Removes an install listener.
+   * @param {string} tag - The identifier for the install listener.
+   * @returns {boolean} True if the listener was removed, false otherwise.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  removeInstallListener(tag) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'removeInstallListener');
+    return this.#installListeners.delete(tag);
+  }
+
+  /**
+   * Retrieves an install listener.
+   * @param {string} tag - The identifier for the install listener.
+   * @returns {LifecycleCallback|undefined} The listener, or undefined if not found.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  getInstallListener(tag) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'getInstallListener');
+    return this.#installListeners.get(tag);
+  }
+
+  /**
+   * Checks if an install listener exists.
+   * @param {string} tag - The identifier for the install listener.
+   * @returns {boolean} True if the listener exists, false otherwise.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  hasInstallListener(tag) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'hasInstallListener');
+    return this.#installListeners.has(tag);
+  }
+
+  /**
+   * Clears all registered install listeners.
+   * @returns {void}
+   */
+  clearInstallListeners() {
+    return this.#installListeners.clear();
+  }
+
+  /**
+   * Gets the number of registered activate listeners.
+   * @returns {number} The count of registered activate listeners.
+   */
+  get activateListenerSize() {
+    return this.#activateListeners.size;
+  }
+
+  /**
+   * Adds an activate listener.
+   * @param {string} tag - The identifier for the activate listener.
+   * @param {LifecycleCallback} callback - The callback to execute.
+   * @returns {void}
+   * @throws {TypeError} If tag is not a non-empty string or callback is not a function.
+   */
+  addActivateListener(tag, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'addActivateListener');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'addActivateListener');
+    this.#activateListeners.set(tag, callback);
+  }
+
+  /**
+   * Removes an activate listener.
+   * @param {string} tag - The identifier for the activate listener.
+   * @returns {boolean} True if the listener was removed, false otherwise.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  removeActivateListener(tag) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'removeActivateListener');
+    return this.#activateListeners.delete(tag);
+  }
+
+  /**
+   * Retrieves an activate listener.
+   * @param {string} tag - The identifier for the activate listener.
+   * @returns {LifecycleCallback|undefined} The listener, or undefined if not found.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  getActivateListener(tag) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'getActivateListener');
+    return this.#activateListeners.get(tag);
+  }
+
+  /**
+   * Checks if an activate listener exists.
+   * @param {string} tag - The identifier for the activate listener.
+   * @returns {boolean} True if the listener exists, false otherwise.
+   * @throws {TypeError} If tag is not a non-empty string.
+   */
+  hasActivateListener(tag) {
+    TinyServiceWorkerEngine.#assertListenerType(tag, 'hasActivateListener');
+    return this.#activateListeners.has(tag);
+  }
+
+  /**
+   * Clears all registered activate listeners.
+   * @returns {void}
+   */
+  clearActivateListeners() {
+    return this.#activateListeners.clear();
+  }
+
+  /**
+   * Removes a registered API handler.
+   * @param {string} type - The identifier for the call.
+   * @returns {boolean} True if the handler was removed, false otherwise.
+   * @throws {TypeError} If type is not a non-empty string.
+   */
+  offApi(type) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'offApi');
+    return this.#apiHandlers.delete(type);
+  }
+
+  /**
+   * Registers a handler for API calls coming from the browser.
+   * @param {string} type - The identifier for the call.
+   * @param {ApiHandlerCallback} callback - Function that processes the request and returns a payload.
+   * @returns {void}
+   * @throws {TypeError} If type is not a non-empty string or callback is not a function.
+   */
+  onApi(type, callback) {
+    TinyServiceWorkerEngine.#assertListenerType(type, 'onApi');
+    TinyServiceWorkerEngine.#assertListenerCallback(callback, 'onApi');
+    this.#apiHandlers.set(type, callback);
+  }
+
+  /**
+   * Sends a request to a specific client in the browser and waits for a response.
+   * @param {Client} client - The client (tab/worker) to which to send.
+   * @param {string} type - The identifier for the call.
+   * @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 any argument has an invalid type.
+   */
+  async emitApi(client, type, data, timeout = 10000) {
+    if (!(client instanceof Client)) {
+      throw new TypeError('[TinyServiceWorkerEngine] emitApi: client must be a valid Client.');
+    }
+    if (typeof type !== 'string' || type.trim() === '') {
+      throw new TypeError('[TinyServiceWorkerEngine] emitApi: type must be a non-empty string.');
+    }
+    if (
+      typeof data !== 'undefined' &&
+      (Array.isArray(data) || typeof data !== 'object' || data === null)
+    ) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] emitApi: data must be a non-null object when provided.',
+      );
+    }
+    if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout < 0) {
+      throw new TypeError(
+        '[TinyServiceWorkerEngine] emitApi: timeout must be a non-negative finite number.',
+      );
+    }
+
+    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 timeout: ${type}`));
+        }
+      }, timeout);
+
+      this.#pendingRequests.set(correlationId, { resolve, reject, timer });
+
+      client.postMessage({
+        type,
+        data,
+        correlationId,
+        isApi: true,
+      });
+    });
+  }
+
+  /**
+   * Handles a `push` event.
+   *
+   * The method never rejects: a failure is reported through the `pushError`
+   * event so the browser does not show its own generic notification.
+   *
+   * @param {PushEvent} event - The native push event.
+   * @returns {Promise<void>}
+   */
+  async #handlePush(event) {
+    const pushCfg = this.#config.push;
+    const message = await TinyPushPayload.fromEvent(event);
+
+    if (TinyPushPayload.isExpired(message)) {
+      this.log('warn', `Discarded expired push: ${message.id ?? message.type}.`);
+      return;
+    }
+
+    /** @type {import('./TinyPushRouter.mjs').TinyPushContext} */
+    const context = { event, message, engine: this, handled: false, notificationShown: false };
+
+    this.emit('push', context);
+
+    /** @type {null|Error} */
+    let errorNotification = null;
+    try {
+      const handled = await this.#pushRouter.dispatch(message, context);
+
+      if (!handled && message.notification) {
+        const { title, options } = TinyPushPayload.toNotification(message, pushCfg);
+        await this.showNotification(title, options.body ?? '', options);
+        context.notificationShown = true;
+      }
+    } catch (error) {
+      const body = errorMaker(error, event);
+      errorNotification = body.error;
+      this.emit('pushError', body);
+      this.log('error', 'Failed to handle push message.', error);
+    } finally {
+      await TinyServiceWorkerEngine.#replyToAll(
+        {
+          type: 'sw:PushReceived',
+          data: {
+            ...message,
+            notificationShown: context.notificationShown === true,
+            error: errorNotification ? errorNotification.message : null,
+          },
+        },
+        false,
+      );
+    }
+  }
+
+  /**
+   * Handles a `notificationclick` event, including action buttons.
+   *
+   * @param {NotificationEvent} event - The native notification click event.
+   * @returns {Promise<void>}
+   */
+  async #handleNotificationClick(event) {
+    const action = event.action || null;
+    const data = /** @type {Record<string, any>} */ (event.notification.data ?? {});
+    const target = action ? data.actions?.[action] : data.url;
+
+    this.emit('notificationclick', { event, action, data });
+
+    if (!target) {
+      event.notification.close();
+      return;
+    }
+
+    const url = new URL(target, sw.location.origin).href;
+    const clientList = await sw.clients.matchAll({ type: 'window', includeUncontrolled: true });
+
+    for (const client of clientList) {
+      if (client.url === url && 'focus' in client) {
+        await client.focus();
+        event.notification.close();
+        return;
+      }
+    }
+
+    await sw.clients.openWindow(url);
+    event.notification.close();
+  }
+
+  /**
+   * Handles a `pushsubscriptionchange` event.
+   *
+   * The browser fires this event when the push service rotates the endpoint.
+   * Without this handler the user stops receiving pushes silently.
+   *
+   * @param {Event} event - The native event.
+   * @returns {Promise<void>}
+   */
+  async #handleSubscriptionChange(event) {
+    this.emit('pushsubscriptionchange', { event });
+    await TinyServiceWorkerEngine.#replyToAll({ type: 'sw:PushSubscriptionChange' }, false);
+  }
+
+  /**
+   * Displays a native notification to the user.
+   *
+   * @param {string} title - The notification title.
+   * @param {string} body - The message body.
+   * @param {NotificationOptions} [options] - Additional options from the Notification API.
+   * @returns {Promise<void>}
+   */
+  async showNotification(title, body, options = {}) {
+    const pushCfg = this.#config.push;
+    if (!pushCfg.enabled) {
+      throw new Error(
+        '[TinyServiceWorkerEngine] showNotification: Push notifications are disabled in the configuration.',
+      );
+    }
+
+    if (typeof title !== 'string' || title.trim() === '') {
+      throw new TypeError('Notification title must be a non-empty string.');
+    }
+    if (typeof body !== 'string') {
+      throw new TypeError('Notification body must be a string.');
+    }
+
+    return sw.registration.showNotification(title, {
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * Runs every registered lifecycle listener and resolves the phase strategy.
+   *
+   * The order is read from `lifecycle.installOrder` or `lifecycle.activateOrder`,
+   * depending on `phase`. Listeners never reject: a throwing listener is logged
+   * and emitted, so it can not block the Service Worker lifecycle.
+   *
+   * @param {Map<string, LifecycleCallback>} listeners - The listeners to run.
+   * @param {ExtendableEvent} event - The native lifecycle event.
+   * @param {'install'|'activate'} phase - The lifecycle phase, used for logging and events.
+   * @param {(event: ExtendableEvent) => Promise<void>} resolveStrategy - Resolves the phase strategy.
+   * @returns {Promise<void>} Resolves once every listener has settled.
+   * @throws {TypeError} If `phase` is unknown or `resolveStrategy` is not a function.
+   */
+  async #runLifecycleListeners(listeners, event, phase, resolveStrategy) {
+    if (typeof resolveStrategy !== 'function') {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] runLifecycleListeners: resolveStrategy must be a function. Received: ${typeof resolveStrategy}`,
+      );
+    }
+
+    const orderKey = PHASE_ORDER_KEY[phase];
+    if (orderKey === undefined) {
+      throw new TypeError(
+        `[TinyServiceWorkerEngine] runLifecycleListeners: unknown phase "${String(phase)}".`,
+      );
+    }
+
+    const strategyFirst = this.#config.lifecycle[orderKey] === 'before';
+
+    if (strategyFirst) await resolveStrategy(event);
+
+    for (const [tag, callback] of listeners.entries()) {
+      try {
+        await callback({ event });
+      } catch (error) {
+        this.log('error', `Error in ${phase} handler for tag "${tag}":`, error);
+        this.emit(`${phase}ListenerError`, { event, tag, error });
+      }
+    }
+
+    if (!strategyFirst) await resolveStrategy(event);
+  }
+
+  /**
+   * Resolves the `install` phase according to the configured strategy.
+   *
+   * @param {ExtendableEvent} event - The native install event.
+   * @returns {Promise<void>}
+   * @throws {TypeError} If the configured install strategy is not recognized.
+   */
+  async #resolveInstall(event) {
+    const { installStrategy } = this.#config.lifecycle;
+
+    switch (installStrategy) {
+      case 'immediate':
+        await this.skipWaiting(event);
+        return;
+      case 'wait':
+        this.log('info', 'install: strategy "wait" active, the worker stays in the waiting state.');
+        return;
+      case 'manual':
+        this.log('info', 'install: strategy "manual" active, call skipWaiting() to activate.');
+        this.emit('waitingForActivation', { event });
+        return;
+      default:
+        throw new TypeError(
+          `[TinyServiceWorkerEngine] resolveInstall: unknown install strategy "${String(installStrategy)}".`,
+        );
+    }
+  }
+
+  /**
+   * Resolves the `activate` phase according to the configured strategy.
+   *
+   * @param {ExtendableEvent} event - The native activate event.
+   * @returns {Promise<void>}
+   * @throws {TypeError} If the configured activate strategy is not recognized.
+   */
+  async #resolveActivate(event) {
+    const { activateStrategy } = this.#config.lifecycle;
+
+    switch (activateStrategy) {
+      case 'immediate':
+        await this.claimClients();
+        return;
+      case 'wait':
+        this.log('info', 'activate: strategy "wait" active, clients will not be claimed.');
+        return;
+      case 'manual':
+        this.log('info', 'activate: strategy "manual" active, call claimClients() to claim.');
+        this.emit('waitingForClaim', { event });
+        return;
+      default:
+        throw new TypeError(
+          `[TinyServiceWorkerEngine] resolveActivate: unknown activate strategy "${String(activateStrategy)}".`,
+        );
+    }
+  }
+
+  /**
+   * Initializes the Service Worker event listeners.
+   * @returns {void}
+   * @throws {Error} If the engine has already been started.
+   */
+  init() {
+    if (this.#started) throw new Error('TinyServiceWorkerEngine is already initialized.');
+
+    // Resolves the install phase according to the configured strategy
+    sw.addEventListener('install', (event) => {
+      event.waitUntil(
+        this.#runLifecycleListeners(this.#installListeners, event, 'install', (e) =>
+          this.#resolveInstall(e),
+        ).catch((err) => this.emit('installError', errorMaker(err, event))),
+      );
+    });
+
+    // Resolves the activate phase according to the configured strategy
+    sw.addEventListener('activate', (event) => {
+      this.emit('beforeActivated', { event });
+      event.waitUntil(
+        this.#runLifecycleListeners(this.#activateListeners, event, 'activate', (e) =>
+          this.#resolveActivate(e),
+        )
+          .then(() => {
+            this.emit('afterActivated', { event });
+            this.log('info', 'Activated.');
+          })
+          .catch((err) => this.emit('activateError', errorMaker(err, event))),
+      );
+    });
+
+    // Listener for Push events
+    const pushCfg = this.#config.push;
+    if (pushCfg.enabled) {
+      sw.addEventListener('push', (event) => {
+        event.waitUntil(
+          this.#handlePush(event).catch((error) => {
+            this.emit('pushError', errorMaker(error, event));
+          }),
+        );
+      });
+
+      sw.addEventListener('notificationclick', (event) => {
+        event.waitUntil(this.#handleNotificationClick(event));
+      });
+
+      sw.addEventListener('notificationclose', (event) => {
+        this.emit('notificationclose', { event });
+      });
+
+      sw.addEventListener('pushsubscriptionchange', (event) => {
+        event.waitUntil(this.#handleSubscriptionChange(event));
+      });
+    }
+
+    // Listener for Sync events
+    const syncCfg = this.#config.sync;
+    if (syncCfg.enabled) {
+      sw.addEventListener('sync', (event) => {
+        const tag = event.tag;
+        const callback = this.#syncListeners.get(tag);
+
+        this.emit('beforeSync', { event, tag });
+
+        if (callback) {
+          event.waitUntil(
+            (async () => {
+              try {
+                await callback({ event, tag });
+                this.emit('afterSync', { event, tag });
+              } catch (error) {
+                this.log('error', `Error in sync handler for tag "${tag}":`, error);
+                this.emit('syncError', { event, tag, error });
+              }
+            })(),
+          );
+        } else {
+          this.emit('afterSync', { event, tag });
+        }
+      });
+    }
+
+    // Detect fetch events on the website.
+    const fetchCfg = this.#config.fetch;
+    if (fetchCfg.enabled) {
+      sw.addEventListener('fetch', (event) => {
+        /** @type {Request} */
+        const request = event.request;
+        const url = new URL(request.url);
+        this.emit('fetchRequested', { event, request, url });
+
+        // Handles navigation requests based on the router configuration.
+        const routerCfg = fetchCfg.router;
+        event.respondWith(
+          (async () => {
+            const fetchResult = await this.#fetchChecker(event, url);
+
+            /**
+             * @param {number} code
+             * @param {string} [customMsg]
+             * @param {string} [customPath]
+             */
+            const buildReply = (code, customMsg, customPath) => {
+              if (routerCfg.enabled) {
+                const resType = getResType(code);
+                const codeCfg = this.getCodeCfg(code);
+                return codeCfg.fn({ code, resType, url, request, event, customMsg, customPath });
+              }
+              return null;
+            };
+
+            // 1. Check if the plugin values are correct
+            if (typeof fetchResult.continueCheck !== 'boolean') {
+              const fetchRes = buildReply(
+                500,
+                'Received fetch result data with invalid continueCheck format (expected boolean).',
+              );
+              if (fetchRes !== null) return fetchRes;
+            }
+
+            if (!fetchResult.continueCheck) return fetch(request);
+
+            if (
+              typeof fetchResult.customPath !== 'undefined' &&
+              typeof fetchResult.customPath !== 'string'
+            ) {
+              const fetchRes = buildReply(
+                500,
+                'Received fetch result data with invalid customPath format (expected string).',
+              );
+              if (fetchRes !== null) return fetchRes;
+            }
+
+            if (
+              typeof fetchResult.customMsg !== 'undefined' &&
+              typeof fetchResult.customMsg !== 'string'
+            ) {
+              const fetchRes = buildReply(
+                500,
+                'Received fetch result data with invalid customMsg format (expected string).',
+              );
+              if (fetchRes !== null) return fetchRes;
+            }
+
+            if (
+              typeof fetchResult.customResponse !== 'undefined' &&
+              !(fetchResult.customResponse instanceof Response)
+            ) {
+              const fetchRes = buildReply(
+                500,
+                'Received fetch result data with invalid customResponse format (expected Response).',
+              );
+              if (fetchRes !== null) return fetchRes;
+            }
+
+            if (typeof fetchResult.needValidation !== 'boolean') {
+              const fetchRes = buildReply(
+                500,
+                'Received fetch result data with invalid needValidation format (expected boolean).',
+              );
+              if (fetchRes !== null) return fetchRes;
+            }
+
+            if (
+              typeof fetchResult.code !== 'number' ||
+              Number.isNaN(fetchResult.code) ||
+              fetchResult.code < 1
+            ) {
+              const fetchRes = buildReply(
+                500,
+                'Received fetch result data with invalid code format (expected number greater than 0).',
+              );
+              if (fetchRes !== null) return fetchRes;
+            }
+
+            // 2. Check if a plugin provided a direct response (e.g., from Cache)
+            if (fetchResult.customResponse instanceof Response) {
+              return fetchResult.customResponse;
+            }
+
+            // 3. Otherwise, proceed with the standard router logic
+            if (fetchResult.needValidation) {
+              const fetchRes = buildReply(
+                fetchResult.code,
+                fetchResult.customMsg,
+                fetchResult.customPath,
+              );
+
+              if (fetchRes !== null) return fetchRes;
+            }
+            return fetch(request);
+          })(),
+        );
+      });
+    }
+
+    // Registers the message event listener for communication with application pages.
+    const msgCfg = this.#config.messaging;
+    if (msgCfg.enabled) {
+      sw.addEventListener('message', (event) => {
+        // Validation: Ensure the source is a valid Client
+        if (!(event.source instanceof Client)) {
+          this.log('error', 'Message received from an invalid source (not a Client).');
+          return;
+        }
+
+        // Validation: Ensure event.data is a non-null object
+        if (Array.isArray(event.data) || typeof event.data !== 'object' || event.data === null) {
+          this.log('error', 'Received message with invalid data format (expected object).');
+          return;
+        }
+        if (
+          typeof event.data.data !== 'undefined' &&
+          (Array.isArray(event.data.data) ||
+            typeof event.data.data !== 'object' ||
+            event.data.data === null)
+        ) {
+          this.log('error', 'Received message data with invalid data format (expected object).');
+          return;
+        }
+
+        // Validation: Ensure 'type' exists and is a string
+        if (typeof event.data.type !== 'string') {
+          this.log('error', 'Received message with missing or invalid "type" string.');
+          return;
+        }
+
+        if (this.#eventBlacklist.has(event.data.type)) {
+          this.log('warn', `Ignored blacklisted event: ${event.data.type}`);
+          return;
+        }
+
+        /** @type {string} */
+        const type = event.data.type;
+        /** @type {MessagePayload|undefined} */
+        const data = event.data.data;
+        /** @type {Client} */
+        const source = event.source;
+        /** @type {string} */
+        const clientId = source.id;
+        /** @type {string} */
+        const correlationId = event.data.correlationId;
+        /** @type {boolean} */
+        const isApi = event.data.isApi;
+
+        /** @type {MessageReply} */
+        const reply = (nType, payload) => {
+          if (!(event.source instanceof Client)) {
+            this.log('warn', 'Attempted to reply to a non-client source.');
+            return;
+          }
+          TinyServiceWorkerEngine.replyTo(event.source, nType, payload);
+        };
+
+        // 1. Handle API responses coming from the Browser (Browser Response -> SW)
+        if (type === 'sw:ApiResponse') {
+          if (typeof correlationId !== 'string') {
+            this.log('error', 'Received message with missing or invalid "correlationId" string.');
+            return;
+          }
+          const pending = this.#pendingRequests.get(correlationId);
+          if (pending) {
+            this.#pendingRequests.delete(correlationId);
+            if (data && data.error) {
+              // Note: The error comes in the 'error' field as defined in the Browser
+              // In the browser, 'error' was sent directly; adjusting for consistency
+              pending.reject(new Error(event.data.error || data.error));
+            } else {
+              pending.resolve(data);
+            }
+          }
+          return;
+        }
+
+        // 2. Handle on-demand activation (Browser Request -> SW)
+        if (type === 'sw:SkipWaiting') {
+          event.waitUntil(
+            this.skipWaiting(event).catch((error) => {
+              this.emit('skipWaitingError', errorMaker(error, event));
+            }),
+          );
+          return;
+        }
+
+        // 3. Handle Browser Notification Clicks (Browser Click -> SW)
+        if (type === 'sw:NotificationClicked') {
+          // We create a pseudo-event that mimics a native NotificationEvent
+          // so that #handleNotificationClick can treat it consistently.
+          /** @type {NotificationEvent} */
+          const pseudoEvent = new MockNotificationEvent(event, {
+            title: data?.title,
+            body: data?.body,
+            options: data?.options,
+          });
+          event.waitUntil(this.#handleNotificationClick(pseudoEvent));
+          return;
+        }
+
+        // 3.1 Handle Browser Notification Closes (Browser Close -> SW)
+        if (type === 'sw:NotificationClosed') {
+          this.emit('notificationclose', { event, data });
+          return;
+        }
+
+        // 4. Handle API calls coming from the Browser (Browser Request -> SW)
+        if (isApi === true) {
+          if (typeof correlationId !== 'string') {
+            this.log('error', 'Received message with missing or invalid "correlationId" string.');
+            return;
+          }
+
+          const handler = this.#apiHandlers.get(type);
+          if (!handler) {
+            source.postMessage({
+              correlationId,
+              type: 'sw:ApiResponse',
+              error: `No API handler registered for type: ${type}`,
+            });
+            return;
+          }
+
+          try {
+            /** @param {MessagePayload} [r] */
+            const sendResult = (r) =>
+              source.postMessage({
+                correlationId,
+                type: 'sw:ApiResponse',
+                data: r,
+              });
+            const result = handler({
+              data,
+              correlationId,
+              clientId,
+              reply,
+              replyTemplate: TinyServiceWorkerEngine.replyTemplate,
+              replyTo: TinyServiceWorkerEngine.replyTo,
+              replyToAll: TinyServiceWorkerEngine.replyToAll,
+              replyApi: async (nType, payload, timeout) => {
+                if (!(event.source instanceof Client)) {
+                  this.log('warn', 'Attempted to reply to a non-client source.');
+                  return;
+                }
+                return this.emitApi(source, nType, payload, timeout);
+              },
+            });
+            if (result instanceof Promise) result.then(sendResult);
+            else sendResult(result);
+          } catch (error) {
+            source.postMessage({
+              correlationId,
+              type: 'sw:ApiResponse',
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+          return;
+        }
+
+        if (event.data.type === 'sw:PrepareUpdate') {
+          this.log('info', 'Update signal received. Starting installation...');
+
+          // Force the browser to fetch the latest version of the SW script
+          this.emit('beforeUpdated', { event });
+          event.waitUntil(
+            sw.registration
+              .update()
+              .then(() => {
+                this.emit('afterUpdated', { event });
+                TinyServiceWorkerEngine.#replyToAll({ type: 'sw:Updated' });
+                this.log('info', 'Update successful, waiting for activation.');
+              })
+              .catch((error) => {
+                const err = error instanceof Error ? error : new Error('Unknown Error.');
+                this.emit('updateError', errorMaker(err, event));
+                TinyServiceWorkerEngine.#replyToAll({
+                  type: 'sw:UpdateError',
+                  data: { message: err.message, name: err.name, stack: err.stack },
+                });
+                this.log('error', 'Update failed:', err);
+              }),
+          );
+        }
+
+        // Get the registered message callback
+        const message = this.#messages.get(type);
+
+        /** @type {MessageObj} */
+        const msgData = {
+          event,
+          data,
+          clientId,
+          reply,
+          replyTemplate: TinyServiceWorkerEngine.replyTemplate,
+          replyTo: TinyServiceWorkerEngine.replyTo,
+          replyToAll: TinyServiceWorkerEngine.replyToAll,
+        };
+
+        /** @type {Error|null} */
+        let err = null;
+
+        // Emit events
+        this.emit('beforeMessage', { event, type, data: msgData });
+        const afterData = () => ({ event, type, error: err, data: msgData });
+        if (message) {
+          /** @param {any} error */
+          const sendErrorEvent = (error) => {
+            err = error instanceof Error ? error : new Error('Unknown Error');
+            this.log('error', `Error executing handler for message type "${type}":`, error);
+            this.emit('messageError', afterData());
+          };
+          try {
+            const callResult = message(msgData);
+            if (callResult instanceof Promise) {
+              event.waitUntil(
+                callResult.then(() => this.emit('afterMessage', afterData())).catch(sendErrorEvent),
+              );
+            } else {
+              this.emit('afterMessage', afterData());
+            }
+          } catch (error) {
+            sendErrorEvent(error);
+          }
+        } else {
+          this.emit('afterMessage', afterData());
+        }
+      });
+    }
+
+    this.#started = true;
+    this.log('info', 'Initialized with custom configuration.');
+  }
+}
+
+module.exports = TinyServiceWorkerEngine;