tiny-essentials 1.19.2 → 1.20.0

package/dist/v1/TinyEssentials.js

@@ -2894,8 +2894,10 @@ __webpack_require__.d(__webpack_exports__, {
   TinyDragger: () => (/* reexport */ libs_TinyDragger),
   TinyEvents: () => (/* reexport */ libs_TinyEvents),
   TinyHtml: () => (/* reexport */ libs_TinyHtml),
+  TinyIframeEvents: () => (/* reexport */ libs_TinyIframeEvents),
   TinyLevelUp: () => (/* reexport */ userLevel),
   TinyLocalStorage: () => (/* reexport */ libs_TinyLocalStorage),
+  TinyNewWinEvents: () => (/* reexport */ libs_TinyNewWinEvents),
   TinyNotifications: () => (/* reexport */ libs_TinyNotifications),
   TinyNotifyCenter: () => (/* reexport */ libs_TinyNotifyCenter),
   TinyPromiseQueue: () => (/* reexport */ libs_TinyPromiseQueue),
@@ -19272,6 +19274,12 @@ class TinyLocalStorage {
   /** @type {Storage} */
   #localStorage = window.localStorage;
 
+  /** @type {string|null} */
+  #dbKey = null;
+
+  /** @type {number} */
+  #version = 0;
+
   /** @type {(ev: StorageEvent) => any} */
   #storageEvent = (ev) => this.emit('storage', ev);
 
@@ -19279,11 +19287,84 @@ class TinyLocalStorage {
    * Initializes the TinyLocalStorage instance and sets up cross-tab sync.
    *
    * Adds listener for the native `storage` event to support tab synchronization.
+   * @param {string} [dbName] - Unique database name.
    */
-  constructor() {
+  constructor(dbName) {
+    if (typeof dbName !== 'undefined' && typeof dbName !== 'string')
+      throw new TypeError('TinyLocalStorage: dbName must be a string if provided.');
+    if (typeof dbName === 'string') this.#dbKey = `LSDB::${dbName}`;
     window.addEventListener('storage', this.#storageEvent);
   }
 
+  /**
+   * Validates that a given key does not conflict with internal database keys.
+   *
+   * This method is used to prevent accidental overwriting of reserved `LSDB::` keys
+   * in `localStorage`, which are used internally by TinyLocalStorage for versioning
+   * and data management.
+   *
+   * @param {string} name - The key to validate before writing to localStorage.
+   * @throws {Error} If the key starts with `LSDB::`.
+   */
+  #isProtectedDbKey(name) {
+    if (typeof name === 'string' && name.startsWith('LSDB::'))
+      throw new Error(`TinyLocalStorage: Key "${name}" may conflict with reserved dbKeys.`);
+  }
+
+  /**
+   * Updates the version of the storage and triggers migration if needed.
+   *
+   * @param {number} version - Desired version of the database.
+   * @param {(oldVersion: number, newVersion: number) => void} onUpgrade - Callback to perform migration logic.
+   * @throws {Error} If the database key has not been initialized.
+   * @throws {TypeError} If `version` is not a valid positive number.
+   * @throws {TypeError} If `onUpgrade` is not a function.
+   */
+  updateStorageVersion(version, onUpgrade) {
+    if (typeof this.#dbKey !== 'string')
+      throw new Error(
+        'TinyLocalStorage: Database key is not initialized. Set a valid dbName in the constructor.',
+      );
+    if (typeof version !== 'number' || Number.isNaN(version) || version < 1)
+      throw new TypeError('TinyLocalStorage: version must be a positive number.');
+    if (typeof onUpgrade !== 'function')
+      throw new TypeError('TinyLocalStorage: onUpgrade must be a function.');
+
+    // @ts-ignore
+    const savedVersion = parseInt(localStorage.getItem(this.#dbKey), 10) || 0;
+    if (typeof savedVersion !== 'number' || Number.isNaN(savedVersion) || savedVersion < 0)
+      throw new TypeError('TinyLocalStorage: saved version in localStorage is not a valid number.');
+
+    if (version < savedVersion)
+      throw new Error(
+        `TinyLocalStorage: Cannot downgrade database version from ${savedVersion} to ${version}.`,
+      );
+
+    if (version > savedVersion) {
+      onUpgrade(savedVersion, version);
+      localStorage.setItem(this.#dbKey, String(version));
+      this.#version = version;
+    }
+  }
+
+  /**
+   * Gets the current database key used in localStorage.
+   *
+   * @returns {string|null} The database key, or null if not set.
+   */
+  getDbKey() {
+    return this.#dbKey;
+  }
+
+  /**
+   * Gets the current version of the database.
+   *
+   * @returns {number} The current version number.
+   */
+  getVersion() {
+    return this.#version;
+  }
+
   /**
    * Defines a custom storage interface (e.g. `sessionStorage`).
    *
@@ -19291,7 +19372,7 @@ class TinyLocalStorage {
    */
   setLocalStorage(localstorage) {
     if (!(localstorage instanceof Storage))
-      throw new Error('Argument must be a valid instance of Storage.');
+      throw new TypeError('Argument must be a valid instance of Storage.');
     this.#localStorage = localstorage;
   }
 
@@ -19313,7 +19394,7 @@ class TinyLocalStorage {
    */
   #setJson(name, data) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     return TinyLocalStorage.encodeSpecialJson(data);
   }
 
@@ -19326,13 +19407,14 @@ class TinyLocalStorage {
    * @param {LocalStorageJsonValue} data - The data to be serialized and stored.
    */
   setJson(name, data) {
+    this.#isProtectedDbKey(name);
     if (
       !isJsonObject(data) &&
       !Array.isArray(data) &&
       !(data instanceof Map) &&
       !(data instanceof Set)
     ) {
-      throw new Error('The storage value is not a valid JSON-compatible structure.');
+      throw new TypeError('The storage value is not a valid JSON-compatible structure.');
     }
     const encoded = this.#setJson(name, data);
     this.emit('setJson', name, data);
@@ -19350,7 +19432,7 @@ class TinyLocalStorage {
    */
   #getJson(name, defaultData) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     const raw = this.#localStorage.getItem(name);
     const fallbackTypes = {
@@ -19404,7 +19486,8 @@ class TinyLocalStorage {
    * @param {Date} data
    */
   setDate(name, data) {
-    if (!(data instanceof Date)) throw new Error('Value must be a Date.');
+    this.#isProtectedDbKey(name);
+    if (!(data instanceof Date)) throw new TypeError('Value must be a Date.');
     const encoded = this.#setJson(name, data);
     this.emit('setDate', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -19426,7 +19509,8 @@ class TinyLocalStorage {
    * @param {RegExp} data
    */
   setRegExp(name, data) {
-    if (!(data instanceof RegExp)) throw new Error('Value must be a RegExp.');
+    this.#isProtectedDbKey(name);
+    if (!(data instanceof RegExp)) throw new TypeError('Value must be a RegExp.');
     const encoded = this.#setJson(name, data);
     this.emit('setRegExp', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -19448,7 +19532,8 @@ class TinyLocalStorage {
    * @param {bigint} data
    */
   setBigInt(name, data) {
-    if (typeof data !== 'bigint') throw new Error('Value must be a BigInt.');
+    this.#isProtectedDbKey(name);
+    if (typeof data !== 'bigint') throw new TypeError('Value must be a BigInt.');
     const encoded = this.#setJson(name, data);
     this.emit('setBigInt', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -19471,7 +19556,8 @@ class TinyLocalStorage {
    * @param {symbol} data
    */
   setSymbol(name, data) {
-    if (typeof data !== 'symbol') throw new Error('Value must be a Symbol.');
+    this.#isProtectedDbKey(name);
+    if (typeof data !== 'symbol') throw new TypeError('Value must be a Symbol.');
     const encoded = this.#setJson(name, data);
     this.emit('setSymbol', name, data);
     return this.#localStorage.setItem(name, JSON.stringify(encoded));
@@ -19504,8 +19590,9 @@ class TinyLocalStorage {
    * @param {any} data - The data to store.
    */
   setItem(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     this.emit('setItem', name, data);
     return this.#localStorage.setItem(name, data);
   }
@@ -19518,7 +19605,7 @@ class TinyLocalStorage {
    */
   getItem(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     return this.#localStorage.getItem(name);
   }
 
@@ -19529,9 +19616,10 @@ class TinyLocalStorage {
    * @param {string} data - The string to store.
    */
   setString(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
-    if (typeof data !== 'string') throw new Error('Value must be a string.');
+      throw new TypeError('Key must be a non-empty string.');
+    if (typeof data !== 'string') throw new TypeError('Value must be a string.');
 
     this.emit('setString', name, data);
     return this.#localStorage.setItem(
@@ -19551,7 +19639,7 @@ class TinyLocalStorage {
    */
   getString(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
     let value = this.#localStorage.getItem(name);
     try {
       /** @type {{ value: string; __string__: boolean }} */
@@ -19573,9 +19661,10 @@ class TinyLocalStorage {
    * @param {number} data - The number to store.
    */
   setNumber(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
-    if (typeof data !== 'number') throw new Error('Value must be a number.');
+      throw new TypeError('Key must be a non-empty string.');
+    if (typeof data !== 'number') throw new TypeError('Value must be a number.');
     this.emit('setNumber', name, data);
     return this.#localStorage.setItem(name, String(data));
   }
@@ -19588,7 +19677,7 @@ class TinyLocalStorage {
    */
   getNumber(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     /** @type {number|string|null} */
     let number = this.#localStorage.getItem(name);
@@ -19607,9 +19696,10 @@ class TinyLocalStorage {
    * @param {boolean} data - The boolean value to store.
    */
   setBool(name, data) {
+    this.#isProtectedDbKey(name);
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
-    if (typeof data !== 'boolean') throw new Error('Value must be a boolean.');
+      throw new TypeError('Key must be a non-empty string.');
+    if (typeof data !== 'boolean') throw new TypeError('Value must be a boolean.');
     this.emit('setBool', name, data);
     return this.#localStorage.setItem(name, String(data));
   }
@@ -19622,7 +19712,7 @@ class TinyLocalStorage {
    */
   getBool(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     const value = this.#localStorage.getItem(name);
     if (typeof value === 'boolean') return value;
@@ -19641,7 +19731,7 @@ class TinyLocalStorage {
    */
   removeItem(name) {
     if (typeof name !== 'string' || !name.length)
-      throw new Error('Key must be a non-empty string.');
+      throw new TypeError('Key must be a non-empty string.');
 
     this.emit('removeItem', name);
     return this.#localStorage.removeItem(name);
@@ -19757,7 +19847,904 @@ TinyLocalStorage.registerJsonType(
 
 /* harmony default export */ const libs_TinyLocalStorage = (TinyLocalStorage);
 
-;// ./src/v1/index.mjs
+;// ./src/v1/libs/TinyIframeEvents.mjs
+
+
+
+/** @type {WeakMap<Window, TinyIframeEvents>} */
+const instances = new WeakMap();
+
+/**
+ * @callback handler
+ * A function to handle incoming event payloads.
+ * @param {any} payload - The data sent by the emitter.
+ * @param {MessageEvent<any>} event - Metadata about the message.
+ */
+
+/**
+ * A flexible event routing system for structured communication
+ * between a parent window and its iframe using `postMessage`.
+ *
+ * This class abstracts the complexity of cross-origin and window-type handling,
+ * allowing both the iframe and parent to:
+ * - Send events with arbitrary payloads
+ * - Listen to specific event names
+ * - Filter events by origin and source
+ * - Work symmetrically from both sides with automatic direction handling
+ *
+ * Use this class when building applications that require modular, event-driven
+ * communication across embedded frames.
+ */
+class TinyIframeEvents {
+  #events = new libs_TinyEvents();
+
+  /**
+   * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+   *
+   * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+   */
+  setThrowOnMaxListeners(shouldThrow) {
+    return this.#events.setThrowOnMaxListeners(shouldThrow);
+  }
+
+  /**
+   * Checks whether an error will be thrown when the max listener limit is exceeded.
+   *
+   * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+   */
+  getThrowOnMaxListeners() {
+    return this.#events.getThrowOnMaxListeners();
+  }
+
+  /////////////////////////////////////////////////////////////
+
+  /**
+   * Adds a listener to the beginning of the listeners array for the specified event.
+   *
+   * @param {string} event - Event name.
+   * @param {handler} handler - The callback function.
+   */
+  prependListener(event, handler) {
+    return this.#events.prependListener(event, handler);
+  }
+
+  /**
+   * Adds a one-time listener to the beginning of the listeners array for the specified event.
+   *
+   * @param {string} event - Event name.
+   * @param {handler} handler - The callback function.
+   * @returns {handler} - The wrapped handler used internally.
+   */
+  prependListenerOnce(event, handler) {
+    return this.#events.prependListenerOnce(event, handler);
+  }
+
+  //////////////////////////////////////////////////////////////////////
+
+  /**
+   * Adds a event listener.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - Callback function to be called when event fires.
+   */
+  appendListener(event, handler) {
+    return this.#events.appendListener(event, handler);
+  }
+
+  /**
+   * Registers an event listener that runs only once, then is removed.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - The callback function to run on event.
+   * @returns {handler} - The wrapped version of the handler.
+   */
+  appendListenerOnce(event, handler) {
+    return this.#events.appendListenerOnce(event, handler);
+  }
+
+  /**
+   * Adds a event listener.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - Callback function to be called when event fires.
+   */
+  on(event, handler) {
+    return this.#events.on(event, handler);
+  }
+
+  /**
+   * Registers an event listener that runs only once, then is removed.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - The callback function to run on event.
+   * @returns {handler} - The wrapped version of the handler.
+   */
+  once(event, handler) {
+    return this.#events.once(event, handler);
+  }
+
+  ////////////////////////////////////////////////////////////////////
+
+  /**
+   * Removes a previously registered event listener.
+   *
+   * @param {string} event - The name of the event to remove the handler from.
+   * @param {handler} handler - The specific callback function to remove.
+   */
+  off(event, handler) {
+    return this.#events.off(event, handler);
+  }
+
+  /**
+   * Removes all event listeners of a specific type from the element.
+   *
+   * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+   */
+  offAll(event) {
+    return this.#events.offAll(event);
+  }
+
+  /**
+   * Removes all event listeners of all types from the element.
+   */
+  offAllTypes() {
+    return this.#events.offAllTypes();
+  }
+
+  ////////////////////////////////////////////////////////////
+
+  /**
+   * Returns the number of listeners for a given event.
+   *
+   * @param {string} event - The name of the event.
+   * @returns {number} Number of listeners for the event.
+   */
+  listenerCount(event) {
+    return this.#events.listenerCount(event);
+  }
+
+  /**
+   * Returns a copy of the array of listeners for the specified event.
+   *
+   * @param {string} event - The name of the event.
+   * @returns {handler[]} Array of listener functions.
+   */
+  listeners(event) {
+    return this.#events.listeners(event);
+  }
+
+  /**
+   * Returns a copy of the array of listeners for the specified event.
+   *
+   * @param {string} event - The name of the event.
+   * @returns {handler[]} Array of listener functions.
+   */
+  onceListeners(event) {
+    return this.#events.onceListeners(event);
+  }
+
+  /**
+   * Returns a copy of the internal listeners array for the specified event,
+   * including wrapper functions like those used by `.once()`.
+   * @param {string | symbol} event - The event name.
+   * @returns {handler[]} An array of raw listener functions.
+   */
+  allListeners(event) {
+    return this.#events.allListeners(event);
+  }
+
+  /**
+   * Returns an array of event names for which there are registered listeners.
+   *
+   * @returns {string[]} Array of registered event names.
+   */
+  eventNames() {
+    return this.#events.eventNames();
+  }
+
+  //////////////////////////////////////////////////////
+
+  /**
+   * Sets the maximum number of listeners per event before a warning is shown.
+   *
+   * @param {number} n - The maximum number of listeners.
+   */
+  setMaxListeners(n) {
+    return this.#events.setMaxListeners(n);
+  }
+
+  /**
+   * Gets the maximum number of listeners allowed per event.
+   *
+   * @returns {number} The maximum number of listeners.
+   */
+  getMaxListeners() {
+    return this.#events.getMaxListeners();
+  }
+
+  ///////////////////////////////////////////////////
+
+  /** @type {Window} */
+  #targetWindow;
+
+  /** @type {string} */
+  #targetOrigin;
+
+  /** @type {string} */
+  #selfType;
+
+  /** @type {boolean} */
+  #isDestroyed = false;
+
+  /** @type {boolean} */
+  #ready = false;
+
+  /**
+   * @typedef {object} IframeEventBase
+   * @property {string} eventName - The name of the custom event route.
+   * @property {any} payload - The data being sent (can be any type).
+   * @property {'iframe' | 'parent'} direction - Indicates the sender: 'iframe' or 'parent'.
+   */
+
+  /**
+   * Queue of messages emitted before connection is ready
+   * @type {IframeEventBase[]}
+   */
+  #pendingQueue = [];
+
+  /** @type {string} Internal message type for routed communication */
+  #secretEventName = '__tinyIframeEvent__';
+
+  /**
+   * Gets the internal secret iframe event name.
+   * @returns {string}
+   */
+  get secretEventName() {
+    return this.#secretEventName;
+  }
+
+  /**
+   * Sets the internal secret iframe event name.
+   * @param {string} name
+   * @throws {TypeError} If the value is not a string.
+   */
+  set secretEventName(name) {
+    if (typeof name !== 'string') throw new TypeError('TinyIframeEvents: secretEventName must be a string.');
+    this.#secretEventName = name;
+  }
+
+  /**
+   * Creates a new TinyIframeEvents instance to manage communication between iframe and parent.
+   * Automatically determines the current context (`iframe` or `parent`) based on the `targetWindow`.
+   *
+   * @param {Object} config - Configuration object.
+   * @param {HTMLIFrameElement} [config.targetIframe] - The target window to post messages to. Defaults to `window.parent` (assumes this is inside an iframe).
+   * @param {string} [config.targetOrigin] - The target origin to restrict messages to. Defaults to `window.location.origin`.
+   */
+  constructor({ targetIframe, targetOrigin } = {}) {
+    if (
+      typeof targetIframe !== 'undefined' &&
+      (!(targetIframe instanceof HTMLIFrameElement) || !targetIframe.contentWindow)
+    )
+      throw new TypeError(
+        `[TinyIframeEvents] Invalid "targetIframe" provided: expected a HTML Iframe Element, received ${typeof targetIframe}`,
+      );
+    if (typeof targetOrigin !== 'undefined' && typeof targetOrigin !== 'string')
+      throw new TypeError(
+        `[TinyIframeEvents] Invalid "targetOrigin" provided: expected a string, received ${typeof targetOrigin}`,
+      );
+
+    this.#targetWindow = targetIframe?.contentWindow ?? window.parent;
+    this.#targetOrigin = targetOrigin ?? window.location.origin;
+    this.#selfType = !targetIframe ? 'iframe' : 'parent';
+    if (instances.has(this.#targetWindow)) throw new Error('Duplicate window reference.');
+
+    this._boundOnMessage = this.#onMessage.bind(this);
+    this._boundOnceMessage = this.#onceMessage.bind(this);
+
+    if (
+      this.#targetWindow.document.readyState === 'complete' ||
+      this.#targetWindow.document.readyState === 'interactive'
+    )
+      this.#onceMessage();
+    else {
+      this.#targetWindow.addEventListener('load', this._boundOnceMessage, false);
+      this.#targetWindow.addEventListener('DOMContentLoaded', this._boundOnceMessage, false);
+    }
+
+    window.addEventListener('message', this._boundOnMessage, false);
+    instances.set(this.#targetWindow, this);
+  }
+
+  /**
+   * Marks the communication as ready and flushes any queued messages.
+   */
+  #onceMessage() {
+    if (this.#ready) return;
+    this.#ready = true;
+    this.#flushQueue();
+  }
+
+  /**
+   * Internal handler for the message event. Filters and dispatches incoming messages.
+   *
+   * @param {MessageEvent<any>} event - The message event received via `postMessage`.
+   */
+  #onMessage(event) {
+    const { data, source } = event;
+
+    // Reject non-object or unrelated messages
+    if (!isJsonObject(data) || !data[this.#secretEventName]) return;
+
+    const { eventName, payload, direction } = data;
+
+    // Reject if not from the expected window (for security)
+    if (source !== this.#targetWindow) return;
+
+    // Reject if direction is not meant for this side
+    if (
+      (this.#selfType === 'iframe' && direction !== 'iframe') ||
+      (this.#selfType === 'parent' && direction !== 'parent')
+    )
+      return;
+
+    this.#events.emit(/** @type {string} */ (eventName), payload, event);
+  }
+
+  /**
+   * Sends an event to the target window.
+   *
+   * @param {string} eventName - A unique name identifying the event.
+   * @param {*} payload - The data to send with the event. Can be any serializable value.
+   * @throws {Error} If `eventName` is not a string.
+   */
+  emit(eventName, payload) {
+    if (typeof eventName !== 'string') throw new TypeError('Event name must be a string.');
+    if (this.#isDestroyed) throw new Error('Cannot emit: instance has been destroyed.');
+
+    /** @type {IframeEventBase} */
+    const message = {
+      [this.#secretEventName]: true,
+      eventName,
+      payload,
+      direction: this.#selfType === 'parent' ? 'iframe' : 'parent',
+    };
+
+    if (!this.#ready) {
+      this.#pendingQueue.push(message);
+      return;
+    }
+
+    this.#targetWindow.postMessage(message, this.#targetOrigin);
+  }
+
+  /**
+   * Sends all pending messages queued before handshake completion.
+   *
+   * @returns {void}
+   */
+  #flushQueue() {
+    while (this.#pendingQueue.length) {
+      const data = this.#pendingQueue.shift();
+      if (data) this.#targetWindow.postMessage(data, this.#targetOrigin);
+    }
+  }
+
+  /**
+   * Checks if the communication instance has been destroyed.
+   *
+   * @returns {boolean}
+   */
+  isDestroyed() {
+    return this.#isDestroyed;
+  }
+
+  /**
+   * Unsubscribes all registered event listeners and removes the message handler.
+   * Call this when the instance is no longer needed to prevent memory leaks.
+   */
+  destroy() {
+    this.#isDestroyed = true;
+    window.removeEventListener('message', this._boundOnMessage);
+    this.#targetWindow.removeEventListener('load', this._boundOnceMessage, false);
+    this.#targetWindow.removeEventListener('DOMContentLoaded', this._boundOnceMessage, false);
+    this.#events.offAllTypes();
+    this.#pendingQueue = [];
+    instances.delete(this.#targetWindow);
+  }
+}
+
+/* harmony default export */ const libs_TinyIframeEvents = (TinyIframeEvents);
+
+;// ./src/v1/libs/TinyNewWinEvents.mjs
+
+
+/**
+ * Stores polling intervals associated with window references.
+ * Used to detect when the window is closed.
+ *
+ * @type {WeakMap<Window, NodeJS.Timeout>}
+ */
+const pollClosedInterval = new WeakMap();
+
+/**
+ * @callback handler
+ * A function to handle incoming event payloads.
+ * @param {any} payload - The data sent by the emitter.
+ * @param {MessageEvent<any>} event - Metadata about the message.
+ */
+
+/**
+ * TinyNewWinEvents provides structured communication between a main window
+ * and a child window (created using window.open) using postMessage.
+ *
+ * It supports routing, queuing messages until handshake is ready,
+ * connection status checks, and close detection.
+ *
+ * @class
+ */
+class TinyNewWinEvents {
+  #events = new libs_TinyEvents();
+
+  /**
+   * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+   *
+   * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+   */
+  setThrowOnMaxListeners(shouldThrow) {
+    return this.#events.setThrowOnMaxListeners(shouldThrow);
+  }
+
+  /**
+   * Checks whether an error will be thrown when the max listener limit is exceeded.
+   *
+   * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+   */
+  getThrowOnMaxListeners() {
+    return this.#events.getThrowOnMaxListeners();
+  }
+
+  /////////////////////////////////////////////////////////////
+
+  /**
+   * Adds a listener to the beginning of the listeners array for the specified event.
+   *
+   * @param {string} event - Event name.
+   * @param {handler} handler - The callback function.
+   */
+  prependListener(event, handler) {
+    return this.#events.prependListener(event, handler);
+  }
+
+  /**
+   * Adds a one-time listener to the beginning of the listeners array for the specified event.
+   *
+   * @param {string} event - Event name.
+   * @param {handler} handler - The callback function.
+   * @returns {handler} - The wrapped handler used internally.
+   */
+  prependListenerOnce(event, handler) {
+    return this.#events.prependListenerOnce(event, handler);
+  }
+
+  //////////////////////////////////////////////////////////////////////
+
+  /**
+   * Adds a event listener.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - Callback function to be called when event fires.
+   */
+  appendListener(event, handler) {
+    return this.#events.appendListener(event, handler);
+  }
+
+  /**
+   * Registers an event listener that runs only once, then is removed.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - The callback function to run on event.
+   * @returns {handler} - The wrapped version of the handler.
+   */
+  appendListenerOnce(event, handler) {
+    return this.#events.appendListenerOnce(event, handler);
+  }
+
+  /**
+   * Adds a event listener.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - Callback function to be called when event fires.
+   */
+  on(event, handler) {
+    return this.#events.on(event, handler);
+  }
+
+  /**
+   * Registers an event listener that runs only once, then is removed.
+   *
+   * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+   * @param {handler} handler - The callback function to run on event.
+   * @returns {handler} - The wrapped version of the handler.
+   */
+  once(event, handler) {
+    return this.#events.once(event, handler);
+  }
+
+  ////////////////////////////////////////////////////////////////////
+
+  /**
+   * Removes a previously registered event listener.
+   *
+   * @param {string} event - The name of the event to remove the handler from.
+   * @param {handler} handler - The specific callback function to remove.
+   */
+  off(event, handler) {
+    return this.#events.off(event, handler);
+  }
+
+  /**
+   * Removes all event listeners of a specific type from the element.
+   *
+   * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+   */
+  offAll(event) {
+    return this.#events.offAll(event);
+  }
+
+  /**
+   * Removes all event listeners of all types from the element.
+   */
+  offAllTypes() {
+    return this.#events.offAllTypes();
+  }
+
+  ////////////////////////////////////////////////////////////
+
+  /**
+   * Returns the number of listeners for a given event.
+   *
+   * @param {string} event - The name of the event.
+   * @returns {number} Number of listeners for the event.
+   */
+  listenerCount(event) {
+    return this.#events.listenerCount(event);
+  }
+
+  /**
+   * Returns a copy of the array of listeners for the specified event.
+   *
+   * @param {string} event - The name of the event.
+   * @returns {handler[]} Array of listener functions.
+   */
+  listeners(event) {
+    return this.#events.listeners(event);
+  }
+
+  /**
+   * Returns a copy of the array of listeners for the specified event.
+   *
+   * @param {string} event - The name of the event.
+   * @returns {handler[]} Array of listener functions.
+   */
+  onceListeners(event) {
+    return this.#events.onceListeners(event);
+  }
+
+  /**
+   * Returns a copy of the internal listeners array for the specified event,
+   * including wrapper functions like those used by `.once()`.
+   * @param {string | symbol} event - The event name.
+   * @returns {handler[]} An array of raw listener functions.
+   */
+  allListeners(event) {
+    return this.#events.allListeners(event);
+  }
+
+  /**
+   * Returns an array of event names for which there are registered listeners.
+   *
+   * @returns {string[]} Array of registered event names.
+   */
+  eventNames() {
+    return this.#events.eventNames();
+  }
+
+  //////////////////////////////////////////////////////
+
+  /**
+   * Sets the maximum number of listeners per event before a warning is shown.
+   *
+   * @param {number} n - The maximum number of listeners.
+   */
+  setMaxListeners(n) {
+    return this.#events.setMaxListeners(n);
+  }
+
+  /**
+   * Gets the maximum number of listeners allowed per event.
+   *
+   * @returns {number} The maximum number of listeners.
+   */
+  getMaxListeners() {
+    return this.#events.getMaxListeners();
+  }
+
+  ///////////////////////////////////////////////////
+
+  /** @type {Window|null} Reference to the opened or parent window */
+  #windowRef;
+
+  /** @type {string} Expected origin for postMessage communication */
+  #targetOrigin;
+
+  /** @type {{ route: string, payload: any }[]} Queue of messages emitted before connection is ready */
+  #pendingQueue = [];
+
+  /** @type {boolean} True if handshake between windows is complete */
+  #ready = false;
+
+  /** @type {boolean} True if this instance is the main window (host) */
+  #isHost = false;
+
+  /** @type {NodeJS.Timeout|null} Interval for polling child window closure */
+  #pollClosedInterval = null;
+
+  /** @type {string} Internal message type for handshake */
+  #readyEventName = '__TNE_READY__';
+
+  /** @type {string} Internal message type for routed communication */
+  #routeEventName = '__TNE_ROUTE__';
+
+  /**
+   * Gets the internal handshake event name.
+   * @returns {string}
+   */
+  get readyEventName() {
+    return this.#readyEventName;
+  }
+
+  /**
+   * Sets the internal handshake event name.
+   * @param {string} name
+   * @throws {TypeError} If the value is not a string.
+   */
+  set readyEventName(name) {
+    if (typeof name !== 'string') throw new TypeError('TinyNewWinEvents: readyEventName must be a string.');
+    this.#readyEventName = name;
+  }
+
+  /**
+   * Gets the internal route event name.
+   * @returns {string}
+   */
+  get routeEventName() {
+    return this.#routeEventName;
+  }
+
+  /**
+   * Sets the internal route event name.
+   * @param {string} name
+   * @throws {TypeError} If the value is not a string.
+   */
+  set routeEventName(name) {
+    if (typeof name !== 'string') throw new TypeError('TinyNewWinEvents: routeEventName must be a string.');
+    this.#routeEventName = name;
+  }
+
+  /**
+   * Initializes a TinyNewWinEvents instance for communication.
+   *
+   * @param {Object} [settings={}] Configuration object.
+   * @param {string} [settings.targetOrigin] Origin to enforce in postMessage.
+   * @param {string} [settings.url] URL string to open.
+   * @param {string} [settings.name] Window name (required if opening a new window).
+   * @param {string} [settings.features] Features string for `window.open`.
+   *
+   * @throws {Error} If `name` is "_blank", which is not allowed.
+   * @throws {TypeError} If `targetOrigin`, `url`, or `features` are not strings (when provided).
+   * @throws {Error} If the window reference is invalid or already being tracked.
+   */
+  constructor({ targetOrigin, url, name, features } = {}) {
+    if (typeof name === 'string' && name === '_blank')
+      throw new Error(
+        'TinyNewWinEvents: The window name "_blank" is not supported. Please use a custom name to allow tracking.',
+      );
+    if (typeof targetOrigin !== 'undefined' && typeof targetOrigin !== 'string')
+      throw new TypeError('TinyNewWinEvents: The "targetOrigin" option must be a string.');
+    if (typeof url !== 'undefined' && typeof url !== 'string')
+      throw new TypeError('TinyNewWinEvents: The "url" option must be a string.');
+    if (typeof features !== 'undefined' && typeof features !== 'string')
+      throw new TypeError('TinyNewWinEvents: The "features" option must be a string if provided.');
+
+    // Open Page
+    if (typeof url === 'undefined') this.#windowRef = window.opener;
+    // Main Page
+    else {
+      this.#windowRef = typeof url === 'string' ? window.open(url, name, features) : url;
+      this.#isHost = true;
+    }
+
+    if (!this.#windowRef || pollClosedInterval.has(this.#windowRef))
+      throw new Error('Invalid or duplicate window reference.');
+    this.#targetOrigin = targetOrigin ?? window.location.origin;
+    this._handleMessage = this.#handleMessage.bind(this);
+    window.addEventListener('message', this._handleMessage, false);
+
+    // Sends handshake if it is host (main window)
+    if (!this.#isHost) {
+      this.#postRaw(this.#readyEventName, null);
+      this.#startCloseWatcher();
+    }
+  }
+
+  /**
+   * Returns the internal window reference.
+   *
+   * @returns {Window|null}
+   */
+  getWin() {
+    return this.#windowRef;
+  }
+
+  /**
+   * Internal message handler.
+   *
+   * @param {MessageEvent} event
+   * @returns {void}
+   */
+  #handleMessage(event) {
+    if (!event.source || (this.#windowRef && event.source !== this.#windowRef)) return;
+    const { type, route, payload } = event.data || {};
+
+    if (type === this.#readyEventName) {
+      this.#ready = true;
+      this.#flushQueue();
+      this.#startCloseWatcher(); // start watcher after handshake (for child window)
+      if (this.#isHost) this.#postRaw(this.#readyEventName, null);
+      return;
+    }
+
+    if (type === this.#routeEventName) this.#events.emit(route, payload, event);
+  }
+
+  /**
+   * Sends all pending messages queued before handshake completion.
+   *
+   * @returns {void}
+   */
+  #flushQueue() {
+    while (this.#pendingQueue.length) {
+      const data = this.#pendingQueue.shift();
+      if (data) {
+        const { route, payload } = data;
+        this.emit(route, payload);
+      }
+    }
+  }
+
+  /**
+   * Sends a raw postMessage with given type and payload.
+   *
+   * @param {string} type Internal message type
+   * @param {any} payload Data to send
+   * @param {string} [route=''] Optional route name
+   * @returns {void}
+   */
+  #postRaw(type, payload, route = '') {
+    if (this.#windowRef && this.#windowRef.closed) return;
+    this.#windowRef?.postMessage({ type, route, payload }, this.#targetOrigin);
+  }
+
+  /**
+   * Closes the child window (only allowed from the host).
+   *
+   * @returns {void}
+   */
+  close() {
+    if (!this.#isHost) throw new Error('Only host can close the window.');
+    if (this.#windowRef && !this.#windowRef.closed) this.#windowRef.close();
+  }
+
+  /**
+   * Emits a message to the other window on a specific route.
+   * If the handshake is not yet complete, the message is queued.
+   * Throws an error if the instance has already been destroyed.
+   *
+   * @param {string} route - Route name used to identify the message handler.
+   * @param {any} payload - Data to send along with the message.
+   * @throws {Error} If the instance is already destroyed.
+   * @returns {void}
+   */
+  emit(route, payload) {
+    if (typeof route !== 'string') throw new TypeError('Event name must be a string.');
+    if (this.isDestroyed()) throw new Error('Cannot emit: instance has been destroyed.');
+    if (!this.#ready) {
+      this.#pendingQueue.push({ route, payload });
+      return;
+    }
+    this.#postRaw(this.#routeEventName, payload, route);
+  }
+
+  /**
+   * Checks if the connection is active and the window is still open.
+   *
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this.#ready && this.#windowRef && !this.#windowRef.closed ? true : false;
+  }
+
+  /**
+   * Starts polling to detect when the window is closed.
+   *
+   * @returns {void}
+   */
+  #startCloseWatcher() {
+    if (!this.#windowRef || this.#pollClosedInterval) return;
+    this.#pollClosedInterval = setInterval(() => {
+      if (this.#windowRef?.closed) {
+        this.#events.emit('WINDOW_REF_CLOSED');
+        this.destroy();
+      }
+    }, 500);
+    pollClosedInterval.set(this.#windowRef, this.#pollClosedInterval);
+  }
+
+  /**
+   * Registers a callback for when the window is closed.
+   *
+   * @param {handler} callback Callback to run on close
+   * @returns {void}
+   */
+  onClose(callback) {
+    return this.#events.on('WINDOW_REF_CLOSED', callback);
+  }
+
+  /**
+   * Unregisters a previously registered close callback.
+   *
+   * @param {handler} callback Callback to remove
+   * @returns {void}
+   */
+  offClose(callback) {
+    return this.#events.off('WINDOW_REF_CLOSED', callback);
+  }
+
+  /**
+   * Checks if the communication instance has been destroyed.
+   *
+   * @returns {boolean}
+   */
+  isDestroyed() {
+    return !this.#windowRef;
+  }
+
+  /**
+   * Destroys the communication instance, cleaning up all resources and listeners.
+   *
+   * @returns {void}
+   */
+  destroy() {
+    if (!this.#windowRef) return;
+    if (this.#pollClosedInterval) {
+      clearInterval(this.#pollClosedInterval);
+      this.#pollClosedInterval = null;
+      pollClosedInterval.delete(this.#windowRef);
+    }
+    window.removeEventListener('message', this._handleMessage);
+    this.#pendingQueue = [];
+    this.#ready = false;
+    this.#windowRef = null;
+    this.#events.offAllTypes();
+  }
+}
+
+/* harmony default export */ const libs_TinyNewWinEvents = (TinyNewWinEvents);
+
+;// ./src/v1/index.mjs
+
+